Merge pull request 'feat: add plugin name prefixes to hooks and improve git-flow sync' (#105) from feat/hook-improvements-and-sync-prune into development

- Add [plugin-name] prefix to all hook messages for better identification
- Make doc-guardian hook notification-only (non-blocking)
- Add stale branch detection to /commit-sync with git fetch --prune
- Enhance /branch-cleanup to handle stale branches separately

Closes improvements for hook UX and git workflow

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -1,27 +1,29 @@
 {
-  "name": "claude-code-marketplace",
+  "name": "leo-claude-mktplace",
   "owner": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
   "metadata": {
     "description": "Project management plugins with Gitea and NetBox integrations",
-    "version": "2.3.0"
+    "version": "3.1.0"
   },
   "plugins": [
     {
       "name": "projman",
-      "version": "2.3.0",
+      "version": "3.1.0",
       "description": "Sprint planning and project management with Gitea integration",
       "source": "./plugins/projman",
       "author": {
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["gitea"],
+      "mcpServers": ["./.mcp.json"],
-      "integrationFile": "claude-md-integration.md"
+      "category": "development",
+      "tags": ["sprint", "agile", "gitea", "project-management"],
+      "license": "MIT"
     },
     {
       "name": "doc-guardian",
@@ -32,11 +34,12 @@
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": [],
+      "hooks": ["./hooks/hooks.json"],
-      "integrationFile": "claude-md-integration.md",
+      "category": "productivity",
-      "hooks": ["PostToolUse", "Stop"]
+      "tags": ["documentation", "drift-detection", "sync"],
+      "license": "MIT"
     },
     {
       "name": "code-sentinel",
@@ -47,11 +50,12 @@
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": [],
+      "hooks": ["./hooks/hooks.json"],
-      "integrationFile": "claude-md-integration.md",
+      "category": "security",
-      "hooks": ["PreToolUse"]
+      "tags": ["security-scan", "refactoring", "vulnerabilities"],
+      "license": "MIT"
     },
     {
       "name": "project-hygiene",
@@ -62,11 +66,12 @@
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": [],
+      "hooks": ["./hooks/hooks.json"],
-      "integrationFile": "claude-md-integration.md",
+      "category": "productivity",
-      "hooks": ["PostToolUse"]
+      "tags": ["cleanup", "automation", "hygiene"],
+      "license": "MIT"
     },
     {
       "name": "cmdb-assistant",
@@ -77,10 +82,12 @@
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": ["netbox"],
+      "mcpServers": ["./.mcp.json"],
-      "integrationFile": "claude-md-integration.md"
+      "category": "infrastructure",
+      "tags": ["cmdb", "netbox", "dcim", "ipam"],
+      "license": "MIT"
     },
     {
       "name": "claude-config-maintainer",
@@ -91,21 +98,57 @@
         "name": "Leo Miranda",
         "email": "leobmiranda@gmail.com"
       },
-      "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
-      "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
-      "mcpServers": [],
+      "category": "development",
-      "integrationFile": "claude-md-integration.md"
+      "tags": ["claude-md", "configuration", "optimization"],
-    }
+      "license": "MIT"
-  ],
-  "pluginDetection": {
-    "mcpServerMapping": {
-      "gitea": "projman",
-      "netbox": "cmdb-assistant"
     },
-    "hookMapping": {
+    {
-      "PostToolUse:Write|Edit": "project-hygiene",
+      "name": "clarity-assist",
-      "PostToolUse:Write|Edit|MultiEdit": "doc-guardian",
+      "version": "1.0.0",
-      "PreToolUse:Write|Edit|MultiEdit": "code-sentinel"
+      "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
-    }
+      "source": "./plugins/clarity-assist",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "productivity",
+      "tags": ["prompts", "requirements", "clarification", "nd-friendly"],
+      "license": "MIT"
+    },
+    {
+      "name": "git-flow",
+      "version": "1.0.0",
+      "description": "Git workflow automation with intelligent commit messages and branch management",
+      "source": "./plugins/git-flow",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "category": "development",
+      "tags": ["git", "workflow", "commits", "branching"],
+      "license": "MIT"
+    },
+    {
+      "name": "pr-review",
+      "version": "1.0.0",
+      "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+      "source": "./plugins/pr-review",
+      "author": {
+        "name": "Leo Miranda",
+        "email": "leobmiranda@gmail.com"
+      },
+      "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
+      "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+      "mcpServers": ["./.mcp.json"],
+      "category": "development",
+      "tags": ["code-review", "pull-requests", "security", "quality"],
+      "license": "MIT"
     }
+  ]
 }

CHANGELOG.md

@@ -1,9 +1,144 @@
 # Changelog
 
-All notable changes to support-claude-mktplace will be documented in this file.
+All notable changes to the Leo Claude Marketplace will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [3.1.1] - 2026-01-22
+
+### Added
+- **git-flow:** `/commit-sync` now prunes stale remote-tracking branches with `git fetch --prune`
+- **git-flow:** `/commit-sync` detects and reports local branches with deleted upstreams
+- **git-flow:** `/branch-cleanup` now handles stale branches (upstream gone) separately from merged branches
+- **git-flow:** New `GIT_CLEANUP_STALE` environment variable for stale branch cleanup control
+
+### Changed
+- **All hooks:** Added `[plugin-name]` prefix to all hook messages for better identification
+  - `[projman]`, `[pr-review]`, `[code-sentinel]`, `[doc-guardian]` prefixes
+- **doc-guardian:** Hook now notification-only (no file reads or blocking operations)
+  - Suggests running `/doc-sync` instead of performing inline checks
+  - Significantly reduces workflow interruption
+
+### Fixed
+- doc-guardian hook no longer stalls workflow with deep file analysis
+
+---
+
+## [3.1.0] - 2026-01-21
+
+### Added
+
+#### Debug Workflow Commands (projman)
+- **`/debug-report`** - Run diagnostics in test projects, create structured issues in marketplace
+  - Runs 5 diagnostic MCP tool tests with explicit repo parameter
+  - Captures full project context (git remote, cwd, branch)
+  - Generates structured issue with hypothesis and investigation steps
+  - Creates issue in configured marketplace repository automatically
+
+- **`/debug-review`** - Investigate diagnostic issues with human approval gates
+  - Lists open diagnostic issues for triage
+  - Maps errors to relevant code files using error-to-file mapping
+  - MANDATORY: Reads relevant files before proposing any fix
+  - Three approval gates: investigation summary, fix approach, PR creation
+  - Creates feature branch, commits, and PR with proper linking
+
+#### MCP Server Improvements
+- Dynamic label format detection in `suggest_labels`
+  - Supports slash format (`Type/Bug`) and colon-space format (`Type: Bug`)
+  - Fetches actual labels from repo and matches suggestions to real format
+  - Handles Effort/Efforts singular/plural normalization
+
+### Changed
+- **`/labels-sync`** completely rewritten with explicit execution steps
+  - Step 1 now explicitly requires running `git remote get-url origin` via Bash
+  - All MCP tool calls show required `repo` parameter
+  - Added "DO NOT" section preventing common mistakes
+  - Removed confusing "Label Reference" section that caused file creation prompts
+
+### Fixed
+- MCP tools no longer fail with "Use 'owner/repo' format" error
+  - Root cause: MCP server is sandboxed and cannot auto-detect project directory
+  - Solution: Command documentation now instructs Claude to detect repo via Bash first
+
+---
+
+## [3.0.1] - 2026-01-21
+
+### Added
+- `/project-init` command for quick project setup when system is already configured
+- `/project-sync` command to sync .env with git remote after repository move/rename
+- SessionStart hooks for automatic mismatch detection between git remote and .env
+- Interactive setup wizard (`/initial-setup`) redesigned to use Claude tools instead of bash script
+
+### Changed
+- `GITEA_ORG` moved from system-level to project-level configuration (different projects may belong to different organizations)
+- Environment variables renamed to match MCP server expectations:
+  - `GITEA_URL` → `GITEA_API_URL` (must include `/api/v1`)
+  - `GITEA_TOKEN` → `GITEA_API_TOKEN`
+  - `NETBOX_URL` → `NETBOX_API_URL` (must include `/api`)
+  - `NETBOX_TOKEN` → `NETBOX_API_TOKEN`
+- Setup commands now validate repository via Gitea API before saving configuration
+- README.md simplified to show only wizard setup path (manual setup moved to CONFIGURATION.md)
+
+### Fixed
+- API URL paths in curl commands (removed redundant `/api/v1` since it's now in the URL variable)
+- Documentation now correctly references environment variable names
+
+---
+
+## [3.0.0] - 2026-01-20
+
+### Added
+
+#### New Plugins
+- **clarity-assist** v1.0.0 - Prompt optimization with ND accommodations
+  - `/clarify` command for full 4-D methodology optimization
+  - `/quick-clarify` command for rapid single-pass clarification
+  - clarity-coach agent with ND-friendly questioning patterns
+  - prompt-patterns skill with optimization rules
+
+- **git-flow** v1.0.0 - Git workflow automation
+  - `/commit` command with smart conventional commit messages
+  - `/commit-push`, `/commit-merge`, `/commit-sync` workflow commands
+  - `/branch-start`, `/branch-cleanup` branch management commands
+  - `/git-status` enhanced status with recommendations
+  - `/git-config` interactive configuration
+  - git-assistant agent for complex operations
+  - workflow-patterns skill with branching strategies
+
+- **pr-review** v1.0.0 - Multi-agent pull request review
+  - `/pr-review` command for comprehensive multi-agent review
+  - `/pr-summary` command for quick PR overview
+  - `/pr-findings` command for filtering review findings
+  - coordinator agent for orchestrating reviews
+  - security-reviewer, performance-analyst, maintainability-auditor, test-validator agents
+  - review-patterns skill with confidence scoring rules
+
+#### Gitea MCP Server Enhancements
+- 6 new Pull Request tools:
+  - `list_pull_requests` - List PRs with filters
+  - `get_pull_request` - Get PR details
+  - `get_pr_diff` - Get PR diff
+  - `get_pr_comments` - Get PR comments
+  - `create_pr_review` - Create review (approve, request changes, comment)
+  - `add_pr_comment` - Add comment to PR
+
+#### Documentation
+- `docs/CONFIGURATION.md` - Centralized configuration guide for all plugins
+
+### Changed
+- **BREAKING:** Marketplace renamed from `claude-code-marketplace` to `leo-claude-mktplace`
+- **BREAKING:** MCP servers moved from plugin directories to shared `mcp-servers/` at repository root
+- All plugins now have `category`, `tags`, and `license` fields in marketplace.json
+- Plugin MCP dependencies now use symlinks to shared servers
+- projman version bumped to 3.0.0 (includes PR tools integration)
+- projman CONFIGURATION.md slimmed down, links to central docs
+
+### Removed
+- Standalone MCP server directories inside plugins (replaced with symlinks)
+
+---
+
 ## [2.3.0] - 2026-01-20
 
 ### Added

CLAUDE.md

@@ -4,15 +4,18 @@ This file provides guidance to Claude Code when working with code in this reposi
 
 ## Project Overview
 
-**Repository:** support-claude-mktplace
+**Repository:** leo-claude-mktplace
-**Version:** 2.3.0
+**Version:** 3.0.1
 **Status:** Production Ready
 
-A Claude Code plugin marketplace containing:
+A plugin marketplace for Claude Code containing:
 
 | Plugin | Description | Version |
 |--------|-------------|---------|
-| `projman` | Sprint planning and project management with Gitea integration | 2.3.0 |
+| `projman` | Sprint planning and project management with Gitea integration | 3.0.0 |
+| `git-flow` | Git workflow automation with smart commits and branch management | 1.0.0 |
+| `pr-review` | Multi-agent PR review with confidence scoring | 1.0.0 |
+| `clarity-assist` | Prompt optimization with ND-friendly accommodations | 1.0.0 |
 | `doc-guardian` | Automatic documentation drift detection and synchronization | 1.0.0 |
 | `code-sentinel` | Security scanning and code refactoring tools | 1.0.0 |
 | `claude-config-maintainer` | CLAUDE.md optimization and maintenance | 1.0.0 |
@@ -25,45 +28,58 @@ A Claude Code plugin marketplace containing:
 # Validate marketplace compliance
 ./scripts/validate-marketplace.sh
 
-# Run projman commands (in a target project with plugin installed)
+# After updates
-/sprint-plan      # Start sprint planning
+./scripts/post-update.sh   # Rebuild venvs, verify symlinks
-/sprint-status    # Check progress
-/review           # Pre-close code quality review
-/test-check       # Verify tests before close
-/sprint-close     # Complete sprint
 ```
 
+### Plugin Commands by Category
+
+| Category | Commands |
+|----------|----------|
+| **Setup** | `/initial-setup`, `/project-init`, `/project-sync` |
+| **Sprint** | `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close` |
+| **Quality** | `/review`, `/test-check`, `/test-gen` |
+| **PR Review** | `/pr-review:initial-setup`, `/pr-review:project-init` |
+| **Docs** | `/doc-audit`, `/doc-sync` |
+| **Security** | `/security-scan`, `/refactor`, `/refactor-dry` |
+| **Config** | `/config-analyze`, `/config-optimize` |
+| **Debug** | `/debug-report`, `/debug-review` |
+
 ## Repository Structure
 
 ```
-support-claude-mktplace/
+leo-claude-mktplace/
 ├── .claude-plugin/
 │   └── marketplace.json          # Marketplace manifest
+├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
+│   ├── gitea/                    # Gitea MCP (issues, PRs, wiki)
+│   └── netbox/                   # NetBox MCP (CMDB)
 ├── plugins/
 │   ├── projman/                  # Sprint management
 │   │   ├── .claude-plugin/plugin.json
 │   │   ├── .mcp.json
-│   │   ├── mcp-servers/gitea/    # Bundled MCP server
+│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
-│   │   ├── commands/             # 9 commands
+│   │   ├── commands/             # 12 commands (incl. setup)
-│   │   │   ├── sprint-plan.md, sprint-start.md, sprint-status.md
+│   │   ├── hooks/                # SessionStart mismatch detection
-│   │   │   ├── sprint-close.md, labels-sync.md, initial-setup.md
-│   │   │   └── review.md, test-check.md, test-gen.md
 │   │   ├── agents/               # 4 agents
-│   │   │   ├── planner.md, orchestrator.md, executor.md
-│   │   │   └── code-reviewer.md
 │   │   └── skills/label-taxonomy/
+│   ├── git-flow/                 # Git workflow automation
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── commands/             # 8 commands
+│   │   └── agents/
+│   ├── pr-review/                # Multi-agent PR review
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── .mcp.json
+│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│   │   ├── commands/             # 6 commands (incl. setup)
+│   │   ├── hooks/                # SessionStart mismatch detection
+│   │   └── agents/               # 5 agents
+│   ├── clarity-assist/           # Prompt optimization (NEW v3.0.0)
+│   │   ├── .claude-plugin/plugin.json
+│   │   ├── commands/             # 2 commands
+│   │   └── agents/
 │   ├── doc-guardian/             # Documentation drift detection
-│   │   ├── .claude-plugin/plugin.json
-│   │   ├── hooks/hooks.json      # PostToolUse, Stop hooks
-│   │   ├── commands/             # doc-audit.md, doc-sync.md
-│   │   ├── agents/               # doc-analyzer.md
-│   │   └── skills/doc-patterns/
 │   ├── code-sentinel/            # Security scanning & refactoring
-│   │   ├── .claude-plugin/plugin.json
-│   │   ├── hooks/hooks.json      # PreToolUse hook
-│   │   ├── commands/             # security-scan.md, refactor.md, refactor-dry.md
-│   │   ├── agents/               # security-reviewer.md, refactor-advisor.md
-│   │   └── skills/security-patterns/
 │   ├── claude-config-maintainer/
 │   ├── cmdb-assistant/
 │   └── project-hygiene/
@@ -72,7 +88,7 @@ support-claude-mktplace/
 │   └── validate-marketplace.sh   # Marketplace compliance validation
 └── docs/
     ├── CANONICAL-PATHS.md        # Single source of truth for paths
-    └── references/
+    └── CONFIGURATION.md          # Centralized configuration guide
 ```
 
 ## CRITICAL: Rules You MUST Follow
@@ -86,7 +102,8 @@ support-claude-mktplace/
 ### Plugin Development
 - **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
 - **Every plugin MUST be listed in marketplace.json**
-- **MCP servers MUST use venv python path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
+- **MCP servers are SHARED at root** with symlinks from plugins
+- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
 - **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
 
 ### Hooks (Valid Events Only)
@@ -98,11 +115,11 @@ support-claude-mktplace/
 `CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
 
 ### Allowed Root Directories
-`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `plugins/`, `scripts/`
+`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
 
 ## Architecture
 
-### Four-Agent Model
+### Four-Agent Model (projman)
 
 | Agent | Personality | Responsibilities |
 |-------|-------------|------------------|
@@ -120,14 +137,17 @@ support-claude-mktplace/
 | 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)* |
 | Validation | `validate_repo_org`, `get_branch_protection` |
 
 ### Hybrid Configuration
 
 | Level | Location | Purpose |
 |-------|----------|---------|
-| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) |
+| System | `~/.config/claude/gitea.env` | Credentials (GITEA_API_URL, GITEA_API_TOKEN) |
-| Project | `.env` in project root | Repository specification (GITEA_REPO) |
+| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) |
+
+**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
 
 ### Branch-Aware Security
 
@@ -160,10 +180,11 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`.
 ### Adding a New Plugin
 
 1. Create `plugins/{name}/.claude-plugin/plugin.json`
-2. Add entry to `.claude-plugin/marketplace.json`
+2. Add entry to `.claude-plugin/marketplace.json` with category, tags, license
 3. Create `README.md` and `claude-md-integration.md`
-4. Run `./scripts/validate-marketplace.sh`
+4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}`
-5. Update `CHANGELOG.md`
+5. Run `./scripts/validate-marketplace.sh`
+6. Update `CHANGELOG.md`
 
 ### Adding a Command to projman
 
@@ -191,40 +212,47 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`.
 | Document | Purpose |
 |----------|---------|
 | `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths |
+| `docs/COMMANDS-CHEATSHEET.md` | All commands quick reference |
+| `docs/CONFIGURATION.md` | Centralized setup guide |
+| `docs/DEBUGGING-CHECKLIST.md` | Systematic troubleshooting guide |
 | `docs/UPDATING.md` | Update guide for the marketplace |
-| `plugins/projman/CONFIGURATION.md` | Projman setup guide |
+| `plugins/projman/CONFIGURATION.md` | Projman quick reference (links to central) |
 | `plugins/projman/README.md` | Projman full documentation |
 
-## Versioning and Changelog Rules
+## Installation Paths
 
-### Version Display
+Understanding where files live is critical for debugging:
-**The marketplace version is displayed ONLY in the main `README.md` title.**
 
-- Format: `# Claude Code Marketplace - vX.Y.Z`
+| Context | Path | Purpose |
-- Do NOT add version numbers to individual plugin documentation titles
+|---------|------|---------|
-- Do NOT add version numbers to configuration guides
+| **Source** | `~/claude-plugins-work/` | Development - edit here |
-- Do NOT add version numbers to CLAUDE.md or other docs
+| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | Runtime - Claude uses this |
+| **Cache** | `~/.claude/` | Plugin metadata and settings |
 
-### Changelog Maintenance (MANDATORY)
+**Key insight:** Edits to source require reinstall/update to take effect at runtime.
-**`CHANGELOG.md` is the authoritative source for version history.**
 
-When releasing a new version:
+## Debugging & Troubleshooting
-1. Update main `README.md` title with new version
-2. Update `CHANGELOG.md` with:
-   - Version number and date: `## [X.Y.Z] - YYYY-MM-DD`
-   - **Added**: New features, commands, files
-   - **Changed**: Modifications to existing functionality
-   - **Fixed**: Bug fixes
-   - **Removed**: Deleted features, files, deprecated items
-3. Update `marketplace.json` metadata version
-4. Update plugin `plugin.json` versions if plugin-specific changes
 
-### Version Format
+See `docs/DEBUGGING-CHECKLIST.md` for systematic troubleshooting.
-- Follow [Semantic Versioning](https://semver.org/): MAJOR.MINOR.PATCH
+
-- MAJOR: Breaking changes
+**Common Issues:**
-- MINOR: New features, backward compatible
+| Symptom | Likely Cause | Fix |
-- PATCH: Bug fixes, minor improvements
+|---------|--------------|-----|
+| "X MCP servers failed" | Missing venv in installed path | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
+| MCP tools not available | Symlink broken or venv missing | Run `/debug-report` to diagnose |
+| Changes not taking effect | Editing source, not installed | Reinstall plugin or edit installed path |
+
+**Debug Commands:**
+- `/debug-report` - Run full diagnostics, create issue if needed
+- `/debug-review` - Investigate and propose fixes
+
+## Versioning Rules
+
+- 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
 
 ---
 
-**Last Updated:** 2026-01-20
+**Last Updated:** 2026-01-22

README.md

@@ -1,15 +1,17 @@
-# Claude Code Marketplace - v2.3.0
+# Leo Claude Marketplace - v3.1.1
 
 A collection of Claude Code plugins for project management, infrastructure automation, and development workflows.
 
 ## Plugins
 
-### [projman](./plugins/projman/README.md)
+### Development & Project Management
+
+#### [projman](./plugins/projman/README.md)
 **Sprint Planning and Project Management**
 
 AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sprint workflow into a distributable plugin.
 
-- Three-agent model: Planner, Orchestrator, Executor, Code Reviewer
+- Four-agent model: Planner, Orchestrator, Executor, Code Reviewer
 - Intelligent label suggestions from 43-label taxonomy
 - Lessons learned capture via Gitea Wiki
 - Native issue dependencies with parallel execution
@@ -17,69 +19,88 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp
 - Branch-aware security (development/staging/production)
 - Pre-sprint-close code quality review and test verification
 
-**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen`
+**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/project-init`, `/project-sync`, `/review`, `/test-check`, `/test-gen`
 
-### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
+#### [git-flow](./plugins/git-flow/README.md) *NEW in v3.0.0*
+**Git Workflow Automation**
+
+Smart git operations with intelligent commit messages and branch management.
+
+- Auto-generated conventional commit messages
+- Multiple workflow styles (simple, feature-branch, pr-required, trunk-based)
+- Branch naming enforcement
+- Merge and cleanup automation
+- Protected branch awareness
+
+**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
+
+#### [pr-review](./plugins/pr-review/README.md) *NEW in v3.0.0*
+**Multi-Agent PR Review**
+
+Comprehensive pull request review using specialized agents.
+
+- Multi-agent review: Security, Performance, Maintainability, Tests
+- Confidence scoring (only reports HIGH/MEDIUM confidence findings)
+- Actionable feedback with suggested fixes
+- Gitea integration for automated review submission
+
+**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`, `/initial-setup`, `/project-init`, `/project-sync`
+
+#### [claude-config-maintainer](./plugins/claude-config-maintainer/README.md)
 **CLAUDE.md Optimization and Maintenance**
 
 Analyze, optimize, and create CLAUDE.md configuration files for Claude Code projects.
 
-- Structure and clarity scoring (100-point system)
-- Automatic optimization with preview and backup
-- Project-aware initialization with stack detection
-- Best practices enforcement
-
 **Commands:** `/config-analyze`, `/config-optimize`, `/config-init`
 
-### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
+### Productivity
-**NetBox CMDB Integration**
 
-Full CRUD operations for network infrastructure management directly from Claude Code.
+#### [clarity-assist](./plugins/clarity-assist/README.md) *NEW in v3.0.0*
+**Prompt Optimization with ND Accommodations**
 
-- Device, IP, site, and rack management
+Transform vague requests into clear specifications using structured methodology.
-- Smart search across all NetBox modules
-- Conversational infrastructure queries
-- Audit trail and change tracking
 
-**Commands:** `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+- 4-D methodology: Deconstruct, Diagnose, Develop, Deliver
+- ND-friendly question patterns (option-based, chunked)
+- Conflict detection and escalation protocols
 
-### [project-hygiene](./plugins/project-hygiene/README.md)
+**Commands:** `/clarify`, `/quick-clarify`
+
+#### [doc-guardian](./plugins/doc-guardian/README.md)
+**Documentation Lifecycle Management**
+
+Automatic documentation drift detection and synchronization.
+
+**Commands:** `/doc-audit`, `/doc-sync`
+
+#### [project-hygiene](./plugins/project-hygiene/README.md)
 **Post-Task Cleanup Automation**
 
 Hook-based cleanup that runs after Claude completes work.
 
-- Deletes temp files (`*.tmp`, `*.bak`, `__pycache__`, etc.)
+### Security
-- Warns about unexpected files in project root
-- Identifies orphaned supporting files
-- Configurable via `.hygiene.json`
 
-### [doc-guardian](./plugins/doc-guardian/README.md)
+#### [code-sentinel](./plugins/code-sentinel/README.md)
-**Documentation Lifecycle Management**
-
-Automatic documentation drift detection and synchronization. Eliminates manual doc update cycles.
-
-- PostToolUse hook detects when code changes affect documentation
-- Stop hook reminds of pending updates before session ends
-- Batched updates in single commit
-
-**Commands:** `/doc-audit`, `/doc-sync`
-
-### [code-sentinel](./plugins/code-sentinel/README.md)
 **Security Scanning & Refactoring**
 
 Security vulnerability detection and code refactoring tools.
 
-- PreToolUse hook catches security issues before code is written
-- Pattern library: SQL injection, XSS, command injection, hardcoded secrets
-- Refactoring patterns: extract method, simplify conditional, modernize syntax
-
 **Commands:** `/security-scan`, `/refactor`, `/refactor-dry`
 
+### Infrastructure
+
+#### [cmdb-assistant](./plugins/cmdb-assistant/README.md)
+**NetBox CMDB Integration**
+
+Full CRUD operations for network infrastructure management directly from Claude Code.
+
+**Commands:** `/initial-setup`, `/cmdb-search`, `/cmdb-device`, `/cmdb-ip`, `/cmdb-site`
+
 ## MCP Servers
 
-MCP servers are **bundled inside each plugin** that needs them. This ensures plugins work when cached by Claude Code.
+MCP servers are **shared at repository root** with **symlinks** from plugins that use them.
 
-### Gitea MCP Server (bundled in projman)
+### Gitea MCP Server (shared)
 
 Full Gitea API integration for project management.
 
@@ -90,9 +111,10 @@ Full Gitea API integration for project management.
 | 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` |
+| **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` |
 
-### NetBox MCP Server (bundled in cmdb-assistant)
+### NetBox MCP Server (shared)
 
 Comprehensive NetBox REST API integration for infrastructure management.
 
@@ -116,7 +138,7 @@ Comprehensive NetBox REST API integration for infrastructure management.
 
 **Option 1 - CLI command (recommended):**
 ```bash
-/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
+/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git
 ```
 
 **Option 2 - Settings file (for team distribution):**
@@ -125,141 +147,117 @@ Add to `.claude/settings.json` in your target project:
 ```json
 {
   "extraKnownMarketplaces": {
-    "support-claude-mktplace": {
+    "leo-claude-mktplace": {
       "source": {
         "source": "git",
-        "url": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git"
+        "url": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git"
       }
     }
   }
 }
 ```
 
-**Option 3 - Local development:**
+### Run Interactive Setup
-```bash
-# Clone the repository first
-git clone https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
 
-# Then add from local path
+After installing plugins, run the setup wizard:
-/plugin marketplace add /path/to/support-claude-mktplace
+
+```
+/initial-setup
 ```
 
-**Alternative SSH URL (for authenticated access):**
+The wizard handles everything:
+- Sets up MCP server (Python venv + dependencies)
+- Creates system config (`~/.config/claude/gitea.env`)
+- Guides you through adding your API token
+- Detects and validates your repository via API
+- Creates project config (`.env`)
+
+**For new projects** (when system is already configured):
 ```
-ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git
+/project-init
 ```
 
-### Configure MCP Server Dependencies
+**After moving a repository:**
-
+```
-If using plugins with MCP servers (projman, cmdb-assistant), install dependencies:
+/project-sync
-
-```bash
-# Gitea MCP (for projman)
-cd plugins/projman/mcp-servers/gitea
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-deactivate
-
-# NetBox MCP (for cmdb-assistant)
-cd ../../../cmdb-assistant/mcp-servers/netbox
-python3 -m venv .venv
-source .venv/bin/activate
-pip install -r requirements.txt
-deactivate
 ```
 
-### Configure Credentials
+See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for manual setup and advanced options.
 
-**System-level credentials:**
+## Verifying Plugin Installation
-```bash
-mkdir -p ~/.config/claude
 
-# Gitea credentials
+After installing plugins, the `/plugin` command may show `(no content)` - this is normal Claude Code behavior and doesn't indicate an error.
-cat > ~/.config/claude/gitea.env << 'EOF'
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=your_token
-GITEA_ORG=your_org
-EOF
 
-# NetBox credentials
+**To verify a plugin is installed correctly:**
-cat > ~/.config/claude/netbox.env << 'EOF'
-NETBOX_API_URL=https://netbox.example.com/api
-NETBOX_API_TOKEN=your_token
-EOF
 
-chmod 600 ~/.config/claude/*.env
+1. **Check installed plugins list:**
-```
+   ```
+   /plugin list
+   ```
+   Look for `✔ plugin-name · Installed`
 
-**Project-level settings:**
+2. **Test a plugin command directly:**
-```bash
+   ```
-# In your target project root
+   /git-flow:git-status
-cat > .env << 'EOF'
+   /projman:sprint-status
-GITEA_REPO=your-repository-name
+   /clarity-assist:clarify
-EOF
+   ```
-```
+   If the command executes and shows output, the plugin is working.
+
+3. **Check for loading errors:**
+   ```
+   /plugin list
+   ```
+   Look for any `Plugin Loading Errors` section - this indicates manifest issues.
+
+**Command format:** All plugin commands use the format `/plugin-name:command-name`
+
+| Plugin | Test Command |
+|--------|--------------|
+| git-flow | `/git-flow:git-status` |
+| projman | `/projman:sprint-status` |
+| pr-review | `/pr-review:pr-summary` |
+| clarity-assist | `/clarity-assist:clarify` |
+| doc-guardian | `/doc-guardian:doc-audit` |
+| code-sentinel | `/code-sentinel:security-scan` |
+| claude-config-maintainer | `/claude-config-maintainer:config-analyze` |
+| cmdb-assistant | `/cmdb-assistant:cmdb-search` |
 
 ## Repository Structure
 
 ```
-support-claude-mktplace/
+leo-claude-mktplace/
 ├── .claude-plugin/                # Marketplace manifest
 │   └── marketplace.json
-├── plugins/                       # All plugins (with bundled MCP servers)
+├── mcp-servers/                   # SHARED MCP servers (v3.0.0+)
-│   ├── projman/                   # Sprint management plugin
+│   ├── gitea/                     # Gitea MCP (issues, PRs, wiki)
-│   │   ├── .claude-plugin/
+│   └── netbox/                    # NetBox MCP (CMDB)
-│   │   ├── .mcp.json
+├── plugins/                       # All plugins
-│   │   ├── mcp-servers/           # Bundled MCP server
+│   ├── projman/                   # Sprint management
-│   │   │   └── gitea/
+│   ├── git-flow/                  # Git workflow automation (NEW)
-│   │   ├── commands/
+│   ├── pr-review/                 # PR review (NEW)
-│   │   ├── agents/
+│   ├── clarity-assist/            # Prompt optimization (NEW)
-│   │   └── skills/
+│   ├── claude-config-maintainer/  # CLAUDE.md optimization
-│   ├── claude-config-maintainer/  # CLAUDE.md optimization plugin
-│   │   ├── .claude-plugin/
-│   │   ├── commands/
-│   │   └── agents/
 │   ├── cmdb-assistant/            # NetBox CMDB integration
-│   │   ├── .claude-plugin/
-│   │   ├── .mcp.json
-│   │   ├── mcp-servers/           # Bundled MCP server
-│   │   │   └── netbox/
-│   │   ├── commands/
-│   │   └── agents/
-│   ├── projman-pmo/               # PMO coordination plugin (planned)
-│   ├── project-hygiene/           # Cleanup automation plugin
 │   ├── doc-guardian/              # Documentation drift detection
-│   └── code-sentinel/             # Security scanning & refactoring
+│   ├── code-sentinel/             # Security scanning
-├── docs/                          # Reference documentation
+│   └── project-hygiene/           # Cleanup automation
-│   ├── CANONICAL-PATHS.md         # Single source of truth for paths
+├── docs/                          # Documentation
-│   └── references/
+│   ├── CANONICAL-PATHS.md         # Path reference
-└── scripts/                       # Setup and maintenance scripts
+│   └── CONFIGURATION.md           # Setup guide
-    └── validate-marketplace.sh    # Marketplace compliance validation
+└── scripts/                       # Setup scripts
 ```
 
-## Key Features
-
-### Parallel Execution
-Tasks are batched by dependency graph for optimal parallel execution:
-```
-Batch 1 (parallel): Task A, Task B, Task C
-Batch 2 (parallel): Task D, Task E  (depend on Batch 1)
-Batch 3 (sequential): Task F        (depends on Batch 2)
-```
-
-### Naming Conventions
-- **Tasks:** `[Sprint XX] <type>: <description>`
-- **Branches:** `feat/`, `fix/`, `debug/` prefixes with issue numbers
-
-### CLI Tools Blocked
-All agents use MCP tools exclusively. CLI tools like `tea` or `gh` are forbidden to ensure consistent, auditable operations.
-
 ## Documentation
 
 | Document | Description |
 |----------|-------------|
 | [CLAUDE.md](./CLAUDE.md) | Main project instructions |
+| [CONFIGURATION.md](./docs/CONFIGURATION.md) | Centralized setup guide |
+| [COMMANDS-CHEATSHEET.md](./docs/COMMANDS-CHEATSHEET.md) | All commands quick reference |
+| [UPDATING.md](./docs/UPDATING.md) | Update guide for the marketplace |
 | [CANONICAL-PATHS.md](./docs/CANONICAL-PATHS.md) | Authoritative path reference |
-| [projman/CONFIGURATION.md](./plugins/projman/CONFIGURATION.md) | Projman setup guide |
+| [CHANGELOG.md](./CHANGELOG.md) | Version history |
 
 ## License
 
@@ -268,5 +266,4 @@ MIT License
 ## Support
 
 - **Issues**: Contact repository maintainer
-- **Repository**: `https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git`
+- **Repository**: `https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git`
-- **SSH URL**: `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git`

docs/CANONICAL-PATHS.md

@@ -2,65 +2,112 @@
 
 **This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
 
-Last Updated: 2026-01-20
+Last Updated: 2026-01-20 (v3.0.0)
 
 ---
 
 ## Repository Root Structure
 
 ```
-support-claude-mktplace/
+leo-claude-mktplace/
 ├── .claude/                    # Claude Code local settings
-├── .claude-plugin/             # Marketplace manifest (claude-code-marketplace)
+├── .claude-plugin/             # Marketplace manifest
 │   └── marketplace.json
 ├── .scratch/                   # Transient work (auto-cleaned)
 ├── docs/                       # All documentation
 │   ├── architecture/           # Draw.io diagrams and specs
 │   ├── CANONICAL-PATHS.md      # This file - single source of truth
+│   ├── CONFIGURATION.md        # Centralized configuration guide
+│   ├── DEBUGGING-CHECKLIST.md  # Systematic troubleshooting guide
 │   ├── UPDATING.md             # Update guide
 │   └── workflows/              # Workflow documentation
 ├── hooks/                      # Shared hooks (if any)
-├── plugins/                    # ALL plugins with bundled MCP servers
+├── mcp-servers/                # SHARED MCP servers (v3.0.0+)
-│   ├── projman/
+│   ├── gitea/                  # Gitea MCP server
+│   │   ├── mcp_server/
+│   │   │   ├── server.py
+│   │   │   ├── gitea_client.py
+│   │   │   ├── config.py
+│   │   │   └── tools/
+│   │   │       ├── issues.py
+│   │   │       ├── labels.py
+│   │   │       ├── wiki.py
+│   │   │       ├── milestones.py
+│   │   │       ├── dependencies.py
+│   │   │       └── pull_requests.py  # NEW in v3.0.0
+│   │   ├── requirements.txt
+│   │   └── .venv/
+│   └── netbox/                 # NetBox MCP server
+│       ├── mcp_server/
+│       ├── requirements.txt
+│       └── .venv/
+├── plugins/                    # ALL plugins
+│   ├── projman/                # Sprint management
 │   │   ├── .claude-plugin/
-│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
+│   │   ├── .mcp.json
-│   │   │   └── gitea/          # Gitea + Wiki tools
+│   │   ├── mcp-servers/
+│   │   │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   │   └── claude-md-integration.md
 │   ├── doc-guardian/           # Documentation drift detection
 │   │   ├── .claude-plugin/
-│   │   ├── hooks/              # PostToolUse, Stop hooks
+│   │   ├── hooks/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
 │   ├── code-sentinel/          # Security scanning & refactoring
 │   │   ├── .claude-plugin/
-│   │   ├── hooks/              # PreToolUse hook
+│   │   ├── hooks/
 │   │   ├── commands/
 │   │   ├── agents/
 │   │   ├── skills/
 │   │   └── claude-md-integration.md
-│   ├── projman-pmo/
+│   ├── cmdb-assistant/         # NetBox CMDB integration
-│   ├── cmdb-assistant/
 │   │   ├── .claude-plugin/
-│   │   ├── mcp-servers/        # MCP servers bundled IN plugin
+│   │   ├── .mcp.json
-│   │   │   └── netbox/
+│   │   ├── mcp-servers/
+│   │   │   └── netbox -> ../../../mcp-servers/netbox  # SYMLINK
 │   │   ├── commands/
 │   │   ├── agents/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   │   └── claude-md-integration.md
 │   ├── claude-config-maintainer/
 │   │   ├── .claude-plugin/
 │   │   ├── commands/
 │   │   ├── agents/
-│   │   └── claude-md-integration.md  # CLAUDE.md integration snippet
+│   │   └── claude-md-integration.md
-│   └── project-hygiene/
+│   ├── project-hygiene/
+│   │   ├── .claude-plugin/
+│   │   ├── hooks/
+│   │   └── claude-md-integration.md
+│   ├── clarity-assist/         # NEW in v3.0.0
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   ├── git-flow/               # NEW in v3.0.0
+│   │   ├── .claude-plugin/
+│   │   ├── commands/
+│   │   ├── agents/
+│   │   ├── skills/
+│   │   └── claude-md-integration.md
+│   └── pr-review/              # NEW in v3.0.0
 │       ├── .claude-plugin/
-│       ├── hooks/
+│       ├── .mcp.json
-│       └── claude-md-integration.md  # CLAUDE.md integration snippet
+│       ├── mcp-servers/
+│       │   └── gitea -> ../../../mcp-servers/gitea  # SYMLINK
+│       ├── commands/
+│       ├── agents/
+│       ├── skills/
+│       └── 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)
+│   └── validate-marketplace.sh # Marketplace compliance validation
 ├── CLAUDE.md
 ├── README.md
 ├── LICENSE
@@ -83,22 +130,26 @@ support-claude-mktplace/
 | Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
 | Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
 
-### MCP Server Paths (Bundled in Plugins)
+### MCP Server Paths (v3.0.0 Architecture)
 
-MCP servers are now **bundled inside each plugin** to ensure they work when plugins are cached.
+MCP servers are **shared at repository root** with **symlinks** from plugins.
 
 | Context | Pattern | Example |
 |---------|---------|---------|
-| MCP server location | `plugins/{plugin}/mcp-servers/{server}/` | `plugins/projman/mcp-servers/gitea/` |
+| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
-| MCP server code | `plugins/{plugin}/mcp-servers/{server}/mcp_server/` | `plugins/projman/mcp-servers/gitea/mcp_server/` |
+| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
-| MCP venv | `plugins/{plugin}/mcp-servers/{server}/.venv/` | `plugins/projman/mcp-servers/gitea/.venv/` |
+| MCP venv | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
+| Plugin symlink | `plugins/{plugin}/mcp-servers/{server}` | `plugins/projman/mcp-servers/gitea` |
 
-### Relative Path Patterns (CRITICAL)
+### Symlink Pattern
 
-| From | To | Pattern |
+Plugins that use MCP servers create symlinks:
-|------|----|---------|
+```bash
-| Plugin .mcp.json | Bundled MCP server | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}` |
+# From plugin directory
-| marketplace.json | Plugin | `./plugins/{plugin-name}` |
+ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
+```
+
+The symlink target is relative: `../../../mcp-servers/{server}`
 
 ### Documentation Paths
 
@@ -108,6 +159,9 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
 | Workflow docs | `docs/workflows/` |
 | This file | `docs/CANONICAL-PATHS.md` |
 | Update guide | `docs/UPDATING.md` |
+| Configuration guide | `docs/CONFIGURATION.md` |
+| Commands cheat sheet | `docs/COMMANDS-CHEATSHEET.md` |
+| Debugging checklist | `docs/DEBUGGING-CHECKLIST.md` |
 
 ---
 
@@ -125,15 +179,15 @@ MCP servers are now **bundled inside each plugin** to ensure they work when plug
 2. Verify each path against patterns in this file
 3. Show verification to user before proceeding
 
-### Relative Path Calculation
+### Relative Path Calculation (v3.0.0)
 
-From `plugins/projman/.mcp.json` to bundled `mcp-servers/gitea/`:
+From `plugins/projman/.mcp.json` to shared `mcp-servers/gitea/`:
 ```
 plugins/projman/.mcp.json
-  → MCP servers are IN the plugin at mcp-servers/
+  → Uses ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
+  → Symlink at plugins/projman/mcp-servers/gitea points to ../../../mcp-servers/gitea
 
-Result: mcp-servers/gitea/
+Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python
-With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
 ```
 
 From `.claude-plugin/marketplace.json` to `plugins/projman/`:
@@ -152,18 +206,28 @@ Result: ./plugins/projman
 | Wrong | Why | Correct |
 |-------|-----|---------|
 | `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
-| `mcp-servers/` at root | MCP servers are bundled in plugins | `plugins/{plugin}/mcp-servers/` |
+| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` |
-| `../../mcp-servers/` from plugin | Old pattern, doesn't work with caching | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` |
+| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
-| `./../../../plugins/projman` in marketplace | Wrong (old nested structure) | `./plugins/projman` |
+| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
 
 ---
 
-## Architecture Note
+## Architecture Note (v3.0.0)
 
-MCP servers are bundled inside each plugin (not shared at root) because:
+MCP servers are now **shared at repository root** with **symlinks** from plugins:
-- Claude Code caches only the plugin directory when installed
+
-- Relative paths to parent directories break in the cache
+**Benefits:**
-- Each plugin must be self-contained to work properly
+- Single source of truth for each MCP server
+- Updates apply to all plugins automatically
+- Reduced duplication
+- Symlinks work with Claude Code caching
+
+**Symlink Pattern:**
+```
+plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
+plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
+plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
+```
 
 ---
 
@@ -171,7 +235,11 @@ MCP servers are bundled inside each plugin (not shared at root) because:
 
 | Date | Change | By |
 |------|--------|-----|
+| 2026-01-20 | v3.0.0: MCP servers moved to root with symlinks | Claude Code |
+| 2026-01-20 | v3.0.0: Added clarity-assist, git-flow, pr-review plugins | Claude Code |
+| 2026-01-20 | v3.0.0: Added docs/CONFIGURATION.md | Claude Code |
+| 2026-01-20 | v3.0.0: Renamed marketplace to leo-claude-mktplace | Claude Code |
 | 2026-01-20 | Removed docs/references/ (obsolete planning docs) | Claude Code |
-| 2026-01-19 | Added claude-md-integration.md path pattern for plugin integration snippets | Claude Code |
+| 2026-01-19 | Added claude-md-integration.md path pattern | Claude Code |
-| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code |
+| 2025-12-15 | Restructured: MCP servers bundled in plugins | Claude Code |
 | 2025-12-12 | Initial creation | Claude Code |

docs/COMMANDS-CHEATSHEET.md

@@ -0,0 +1,217 @@
+# Plugin Commands Cheat Sheet
+
+Quick reference for all commands in the Leo Claude Marketplace.
+
+---
+
+## Command Reference Table
+
+| Plugin | Command | Auto | Manual | Description |
+|--------|---------|:----:|:------:|-------------|
+| **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation |
+| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination |
+| **projman** | `/sprint-status` | | X | Check current sprint progress and identify blockers |
+| **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
+| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
+| **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
+| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
+| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config |
+| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
+| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
+| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync |
+| **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
+| **projman** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
+| **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
+| **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
+| **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation |
+| **git-flow** | `/commit-merge` | | X | Commit current changes, then merge into target branch |
+| **git-flow** | `/commit-sync` | | X | Full sync: commit, push, and sync with upstream/base branch |
+| **git-flow** | `/branch-start` | | X | Create new feature/fix/chore branch with naming conventions |
+| **git-flow** | `/branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
+| **git-flow** | `/git-status` | | X | Enhanced git status with recommendations |
+| **git-flow** | `/git-config` | | X | Configure git-flow settings for the project |
+| **pr-review** | `/initial-setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) |
+| **pr-review** | `/project-init` | | X | Quick project setup for PR reviews |
+| **pr-review** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
+| **pr-review** | *SessionStart hook* | X | | Detects git remote vs .env mismatch |
+| **pr-review** | `/pr-review` | | X | Full multi-agent PR review with confidence scoring |
+| **pr-review** | `/pr-summary` | | X | Quick summary of PR changes |
+| **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity |
+| **clarity-assist** | `/clarify` | | X | Full 4-D prompt optimization with ND accommodations |
+| **clarity-assist** | `/quick-clarify` | | X | Rapid single-pass clarification for simple requests |
+| **doc-guardian** | `/doc-audit` | | X | Full documentation audit - scans for doc drift |
+| **doc-guardian** | `/doc-sync` | | X | Synchronize pending documentation updates |
+| **doc-guardian** | *PostToolUse hook* | X | | Silently detects doc drift on Write/Edit |
+| **code-sentinel** | `/security-scan` | | X | Full security audit (SQL injection, XSS, secrets, etc.) |
+| **code-sentinel** | `/refactor` | | X | Apply refactoring patterns to improve code |
+| **code-sentinel** | `/refactor-dry` | | X | Preview refactoring without applying changes |
+| **code-sentinel** | *PreToolUse hook* | X | | Scans code before writing; blocks critical issues |
+| **claude-config-maintainer** | `/config-analyze` | | X | Analyze CLAUDE.md for optimization opportunities |
+| **claude-config-maintainer** | `/config-optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
+| **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project |
+| **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server |
+| **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites |
+| **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
+| **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes |
+| **cmdb-assistant** | `/cmdb-site` | | X | Manage sites, locations, racks, and regions |
+| **project-hygiene** | *PostToolUse hook* | X | | Removes temp files, warns about unexpected root files |
+
+---
+
+## Plugins by Category
+
+| Category | Plugins | Primary Use |
+|----------|---------|-------------|
+| **Setup** | projman, pr-review, cmdb-assistant | `/initial-setup`, `/project-init` |
+| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
+| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
+| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
+| **Git Operations** | git-flow | Commits, branches, workflow automation |
+| **Infrastructure** | cmdb-assistant | NetBox CMDB management |
+| **Maintenance** | project-hygiene | Automatic cleanup |
+
+---
+
+## Hook-Based Automation Summary
+
+| Plugin | Hook Event | Behavior |
+|--------|------------|----------|
+| **projman** | SessionStart | Checks git remote vs .env; warns if mismatch detected |
+| **pr-review** | SessionStart | Checks git remote vs .env; warns if mismatch detected |
+| **doc-guardian** | PostToolUse (Write/Edit) | Silently tracks documentation drift |
+| **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities |
+| **project-hygiene** | PostToolUse (Write/Edit) | Cleans temp files, warns about misplaced files |
+
+---
+
+## Dev Workflow Examples
+
+### Example 1: Starting a New Feature Sprint
+
+A typical workflow for planning and executing a feature sprint:
+
+```
+1. /clarify                  # Clarify requirements if vague
+2. /sprint-plan              # Plan the sprint with architecture analysis
+3. /labels-sync              # Ensure labels are up-to-date
+4. /sprint-start             # Begin execution with dependency ordering
+5. /branch-start feat/...    # Create feature branch
+   ... implement features ...
+6. /commit                   # Commit with conventional message
+7. /sprint-status            # Check progress mid-sprint
+8. /review                   # Pre-close quality review
+9. /test-check               # Verify test coverage
+10. /sprint-close            # Capture lessons learned
+```
+
+### Example 2: Daily Development Cycle
+
+Quick daily workflow with git-flow:
+
+```
+1. /git-status               # Check current state
+2. /branch-start fix/...     # Start bugfix branch
+   ... make changes ...
+3. /commit                   # Auto-generate commit message
+4. /commit-push              # Push to remote
+5. /branch-cleanup           # Clean merged branches
+```
+
+### Example 3: Pull Request Review Workflow
+
+Reviewing a PR before merge:
+
+```
+1. /pr-summary               # Quick overview of changes
+2. /pr-review                # Full multi-agent review
+3. /pr-findings              # Filter findings by severity
+4. /security-scan            # Deep security audit if needed
+```
+
+### Example 4: Documentation Maintenance
+
+Keeping docs in sync:
+
+```
+1. /doc-audit                # Scan for documentation drift
+2. /doc-sync                 # Apply pending updates
+3. /config-analyze           # Check CLAUDE.md health
+4. /config-optimize          # Optimize if needed
+```
+
+### Example 5: Code Refactoring Session
+
+Safe refactoring with preview:
+
+```
+1. /refactor-dry             # Preview opportunities
+2. /security-scan            # Baseline security check
+3. /refactor                 # Apply improvements
+4. /test-check               # Verify nothing broke
+5. /commit                   # Commit with descriptive message
+```
+
+### Example 6: Infrastructure Documentation
+
+Managing infrastructure with CMDB:
+
+```
+1. /cmdb-search "server"     # Find existing devices
+2. /cmdb-device view X       # Check device details
+3. /cmdb-ip list             # List available IPs
+4. /cmdb-site view Y         # Check site info
+```
+
+### Example 7: First-Time Setup (New Machine)
+
+Setting up the marketplace for the first time:
+
+```
+1. /initial-setup            # Full setup: MCP + system config + project
+   # → Follow prompts for Gitea URL, org
+   # → Add token manually when prompted
+   # → Confirm repository name
+2. # Restart Claude Code session
+3. /labels-sync              # Sync Gitea labels
+4. /sprint-plan              # Plan first sprint
+```
+
+### Example 8: New Project Setup (System Already Configured)
+
+Adding a new project when system config exists:
+
+```
+1. /project-init             # Quick project setup
+   # → Confirms detected repo name
+   # → Creates .env
+2. /labels-sync              # Sync Gitea labels
+3. /sprint-plan              # Plan first sprint
+```
+
+---
+
+## Quick Tips
+
+- **Hooks run automatically** - doc-guardian and code-sentinel protect you without manual invocation
+- **Use `/commit` over `git commit`** - generates better commit messages following conventions
+- **Run `/review` before `/sprint-close`** - catches issues before closing the sprint
+- **Use `/clarify` for vague requests** - especially helpful for complex requirements
+- **`/refactor-dry` is safe** - always preview before applying refactoring changes
+
+---
+
+## MCP Server Requirements
+
+Some plugins require MCP server connectivity:
+
+| Plugin | MCP Server | Purpose |
+|--------|------------|---------|
+| projman | Gitea | Issues, PRs, wiki, labels, milestones |
+| pr-review | Gitea | PR operations and reviews |
+| cmdb-assistant | NetBox | Infrastructure CMDB |
+
+Ensure credentials are configured in `~/.config/claude/gitea.env` or `~/.config/claude/netbox.env`.
+
+---
+
+*Last Updated: 2026-01-22*

docs/CONFIGURATION.md

@@ -0,0 +1,547 @@
+# Configuration Guide
+
+Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.
+
+---
+
+## Quick Start
+
+**After installing the marketplace and plugins via Claude Code:**
+
+```
+/initial-setup
+```
+
+The interactive wizard handles everything except manually adding your API tokens.
+
+---
+
+## Setup Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           FIRST TIME SETUP                                  │
+│                         (once per machine)                                  │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+                            /initial-setup
+                                    │
+     ┌──────────────────────────────┼──────────────────────────────┐
+     ▼                              ▼                              ▼
+┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
+│  PHASE 1    │            │    PHASE 2      │            │    PHASE 3      │
+│  Automated  │───────────▶│    Automated    │───────────▶│   Interactive   │
+│             │            │                 │            │                 │
+│ • Check     │            │ • Find MCP path │            │ • Ask Gitea URL │
+│   Python    │            │ • Create venv   │            │ • Ask Org name  │
+│   version   │            │ • Install deps  │            │ • Create config │
+└─────────────┘            └─────────────────┘            └─────────────────┘
+                                                                   │
+                                                                   ▼
+                                                   ┌───────────────────────────┐
+                                                   │        PHASE 4            │
+                                                   │     USER ACTION           │
+                                                   │                           │
+                                                   │  Edit config file to add  │
+                                                   │  API token (for security) │
+                                                   │                           │
+                                                   │  nano ~/.config/claude/   │
+                                                   │       gitea.env           │
+                                                   └───────────────────────────┘
+                                                                   │
+                                                                   ▼
+     ┌──────────────────────────────┬──────────────────────────────┐
+     ▼                              ▼                              ▼
+┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
+│  PHASE 5    │            │    PHASE 6      │            │    PHASE 7      │
+│ Interactive │            │    Automated    │            │    Automated    │
+│             │            │                 │            │                 │
+│ • Confirm   │            │ • Create .env   │            │ • Test API      │
+│   repo name │            │ • Check         │            │ • Show summary  │
+│   from git  │            │   .gitignore    │            │ • Restart note  │
+└─────────────┘            └─────────────────┘            └─────────────────┘
+                                                                   │
+                                                                   ▼
+                                                   ┌───────────────────────────┐
+                                                   │      RESTART SESSION      │
+                                                   │                           │
+                                                   │  MCP tools available      │
+                                                   │  after restart            │
+                                                   └───────────────────────────┘
+
+
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                          NEW PROJECT SETUP                                  │
+│                        (once per project)                                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    ▼                               ▼
+             /project-init                   /initial-setup
+             (direct path)                   (smart detection)
+                    │                               │
+                    │                    ┌──────────┴──────────┐
+                    │                    ▼                     ▼
+                    │              "Quick setup"         "Full setup"
+                    │               (skips to              (re-runs
+                    │              project config)          everything)
+                    │                    │                     │
+                    └────────────────────┴─────────────────────┘
+                                         │
+                                         ▼
+                              ┌─────────────────────┐
+                              │   PROJECT CONFIG    │
+                              │                     │
+                              │ • Detect repo from  │
+                              │   git remote        │
+                              │ • Confirm with user │
+                              │ • Create .env       │
+                              │ • Check .gitignore  │
+                              └─────────────────────┘
+                                         │
+                                         ▼
+                                      Done!
+```
+
+---
+
+## What Runs Automatically vs User Interaction
+
+### `/initial-setup` - Full Setup
+
+| Phase | Type | What Happens |
+|-------|------|--------------|
+| **1. Environment Check** | Automated | Verifies Python 3.10+ is installed |
+| **2. MCP Server Setup** | Automated | Finds plugin path, creates venv, installs dependencies |
+| **3. System Config Creation** | Interactive | Asks for Gitea URL and organization name |
+| **4. Token Entry** | **User Action** | User manually edits config file to add API token |
+| **5. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
+| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
+| **7. Validation** | Automated | Tests API connectivity, shows summary |
+
+### `/project-init` - Quick Project Setup
+
+| Phase | Type | What Happens |
+|-------|------|--------------|
+| **1. Pre-flight Check** | Automated | Verifies system config exists |
+| **2. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
+| **3. Project Config** | Automated | Creates/updates `.env` file |
+| **4. Gitignore Check** | Interactive | Asks to add `.env` to `.gitignore` if missing |
+
+---
+
+## Three Commands for Different Scenarios
+
+| Command | When to Use | What It Does |
+|---------|-------------|--------------|
+| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config |
+| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) |
+| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
+
+**Typical workflow:**
+1. Install plugin → run `/initial-setup` (once per machine)
+2. Start new project → run `/project-init` (once per project)
+3. Repository moved? → run `/project-sync` (updates config)
+
+**Smart features:**
+- `/initial-setup` detects existing system config and offers quick project setup
+- All commands validate org/repo via Gitea API before saving (auto-fills if verified)
+- SessionStart hook automatically detects git remote vs .env mismatches
+
+---
+
+## Configuration Architecture
+
+This marketplace uses a **hybrid configuration** approach:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SYSTEM-LEVEL (once per machine)             │
+│                    ~/.config/claude/                            │
+├─────────────────────────────────────────────────────────────────┤
+│  gitea.env     │  GITEA_API_URL, GITEA_API_TOKEN                       │
+│  netbox.env    │  NETBOX_API_URL, NETBOX_API_TOKEN                     │
+│  git-flow.env  │  GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc.   │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              │ Shared across all projects
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                  PROJECT-LEVEL (once per project)              │
+│                  <project-root>/.env                            │
+├─────────────────────────────────────────────────────────────────┤
+│  GITEA_ORG               │  Organization for this project      │
+│  GITEA_REPO              │  Repository name for this project   │
+│  GIT_WORKFLOW_STYLE      │  (optional) Override system default │
+│  PR_REVIEW_*             │  (optional) PR review settings      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Benefits:**
+- Single token per service (update once, use everywhere)
+- Easy multi-project setup (just run `/project-init` in each project)
+- Security (tokens never committed to git, never typed into AI chat)
+- Project isolation (each project can override defaults)
+
+---
+
+## Prerequisites
+
+Before running `/initial-setup`:
+
+1. **Python 3.10+** installed
+   ```bash
+   python3 --version  # Should be 3.10.0 or higher
+   ```
+
+2. **Git repository** initialized (for project setup)
+   ```bash
+   git status  # Should show initialized repository
+   ```
+
+3. **Claude Code** installed and working with the marketplace
+
+---
+
+## Setup Methods
+
+### Method 1: Interactive Wizard (Recommended)
+
+Run the setup wizard in Claude Code:
+
+```
+/initial-setup
+```
+
+The wizard will guide you through each step interactively.
+
+**Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
+
+### Method 2: Manual Setup
+
+If you prefer to set up manually or need to troubleshoot:
+
+#### Step 1: MCP Server Setup
+
+```bash
+# Navigate to marketplace directory
+cd /path/to/leo-claude-mktplace
+
+# Set up Gitea MCP server
+cd mcp-servers/gitea
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+
+# (Optional) Set up NetBox MCP server
+cd ../netbox
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+```
+
+#### Step 2: System Configuration
+
+```bash
+mkdir -p ~/.config/claude
+
+# Gitea configuration (credentials only)
+cat > ~/.config/claude/gitea.env << 'EOF'
+GITEA_API_URL=https://gitea.example.com
+GITEA_API_TOKEN=your_token_here
+EOF
+chmod 600 ~/.config/claude/gitea.env
+```
+
+#### Step 3: Project Configuration
+
+In each project root:
+
+```bash
+cat > .env << 'EOF'
+GITEA_ORG=your-organization
+GITEA_REPO=your-repo-name
+EOF
+```
+
+Add `.env` to `.gitignore` if not already there.
+
+### Method 3: Automation Script (CI/Scripting)
+
+For automated setups or CI environments:
+
+```bash
+cd /path/to/leo-claude-mktplace
+./scripts/setup.sh
+```
+
+This script is useful for CI/CD pipelines and bulk provisioning.
+
+---
+
+## Configuration Reference
+
+### System-Level Files
+
+Located in `~/.config/claude/`:
+
+| File | Required By | Purpose |
+|------|-------------|---------|
+| `gitea.env` | projman, pr-review | Gitea API credentials |
+| `netbox.env` | cmdb-assistant | NetBox API credentials |
+| `git-flow.env` | git-flow | Default git workflow settings |
+
+### Gitea Configuration
+
+```bash
+# ~/.config/claude/gitea.env
+GITEA_API_URL=https://gitea.example.com/api/v1
+GITEA_API_TOKEN=your_gitea_token_here
+```
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `GITEA_API_URL` | Gitea API endpoint (with `/api/v1`) | `https://gitea.example.com/api/v1` |
+| `GITEA_API_TOKEN` | Personal access token | `abc123...` |
+
+**Note:** `GITEA_ORG` is configured at the project level (see below) since different projects may belong to different organizations.
+
+**Generating a Gitea Token:**
+1. Log into Gitea → **User Icon** → **Settings**
+2. **Applications** tab → **Manage Access Tokens**
+3. **Generate New Token** with permissions:
+   - `repo` (all sub-permissions)
+   - `read:org`
+   - `read:user`
+   - `write:repo` (for wiki access)
+4. Copy token immediately (shown only once)
+
+### NetBox Configuration
+
+```bash
+# ~/.config/claude/netbox.env
+NETBOX_API_URL=https://netbox.example.com
+NETBOX_API_TOKEN=your_netbox_token_here
+```
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `NETBOX_API_URL` | NetBox base URL | `https://netbox.example.com` |
+| `NETBOX_API_TOKEN` | API token | `abc123...` |
+
+### Git-Flow Configuration
+
+```bash
+# ~/.config/claude/git-flow.env
+GIT_WORKFLOW_STYLE=feature-branch
+GIT_DEFAULT_BASE=development
+GIT_AUTO_DELETE_MERGED=true
+GIT_AUTO_PUSH=false
+GIT_PROTECTED_BRANCHES=main,master,development,staging,production
+GIT_COMMIT_STYLE=conventional
+GIT_CO_AUTHOR=true
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy |
+| `GIT_DEFAULT_BASE` | `development` | Default base branch |
+| `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches |
+| `GIT_AUTO_PUSH` | `false` | Auto-push after commit |
+| `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches |
+| `GIT_COMMIT_STYLE` | `conventional` | Commit message style |
+| `GIT_CO_AUTHOR` | `true` | Include Claude co-author |
+
+---
+
+## Project-Level Configuration
+
+Create `.env` in each project root:
+
+```bash
+# Required for projman, pr-review
+GITEA_ORG=your-organization
+GITEA_REPO=your-repo-name
+
+# Optional: Override git-flow defaults
+GIT_WORKFLOW_STYLE=pr-required
+GIT_DEFAULT_BASE=main
+
+# Optional: PR review settings
+PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
+PR_REVIEW_AUTO_SUBMIT=false
+```
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITEA_ORG` | Yes | Gitea organization for this project |
+| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
+| `GIT_WORKFLOW_STYLE` | No | Override system default |
+| `PR_REVIEW_*` | No | PR review settings |
+
+---
+
+## Plugin Configuration Summary
+
+| Plugin | System Config | Project Config | Setup Commands |
+|--------|---------------|----------------|----------------|
+| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
+| **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
+| **clarity-assist** | None | None | None needed |
+| **cmdb-assistant** | netbox.env | None | `/initial-setup` |
+| **doc-guardian** | None | None | None needed |
+| **code-sentinel** | None | None | None needed |
+| **project-hygiene** | None | None | None needed |
+| **claude-config-maintainer** | None | None | None needed |
+
+---
+
+## Multi-Project Workflow
+
+Once system-level config is set up, adding new projects is simple:
+
+**Option 1: Use `/project-init` (faster)**
+```
+cd ~/projects/new-project
+/project-init
+```
+
+**Option 2: Use `/initial-setup` (auto-detects)**
+```
+cd ~/projects/new-project
+/initial-setup
+# → Detects system config exists
+# → Offers "Quick project setup" option
+```
+
+Both approaches work. Use `/project-init` when you know the system is already configured.
+
+---
+
+## Automatic Validation Features
+
+### API Validation
+
+When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
+
+1. **Detect** organization and repository from git remote URL
+2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
+3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
+4. **Ask for confirmation** only if validation fails (404 or permission error)
+
+This catches typos and permission issues before saving configuration.
+
+### Mismatch Detection (SessionStart Hook)
+
+When you start a Claude Code session, a hook automatically:
+
+1. Reads `GITEA_ORG` and `GITEA_REPO` from `.env`
+2. Compares with current `git remote get-url origin`
+3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update."
+
+This helps when you:
+- Move a repository to a different organization
+- Rename a repository
+- Clone a repo but forget to update `.env`
+
+---
+
+## Verification
+
+### Test Gitea Connection
+
+```bash
+source ~/.config/claude/gitea.env
+curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"
+```
+
+### Verify Project Setup
+
+In Claude Code, after restarting your session:
+```
+/labels-sync
+```
+
+If this works, your setup is complete.
+
+---
+
+## Troubleshooting
+
+### MCP tools not available
+
+**Cause:** Session wasn't restarted after setup.
+**Solution:** Exit Claude Code and start a new session.
+
+### "Configuration not found" error
+
+```bash
+# Check system config exists
+ls -la ~/.config/claude/gitea.env
+
+# Check permissions (should be 600)
+stat ~/.config/claude/gitea.env
+```
+
+### Authentication failed
+
+```bash
+# Test token directly
+source ~/.config/claude/gitea.env
+curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"
+```
+
+If you get 401, regenerate your token in Gitea.
+
+### MCP server won't start
+
+```bash
+# Check venv exists
+ls /path/to/mcp-servers/gitea/.venv
+
+# Reinstall if missing
+cd /path/to/mcp-servers/gitea
+rm -rf .venv
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+deactivate
+```
+
+### Wrong repository
+
+```bash
+# Check project .env
+cat .env
+
+# Verify GITEA_REPO matches the Gitea repository name exactly
+```
+
+---
+
+## Security Best Practices
+
+1. **Never commit tokens**
+   - Keep credentials in `~/.config/claude/` only
+   - Add `.env` to `.gitignore`
+
+2. **Secure configuration files**
+   ```bash
+   chmod 600 ~/.config/claude/*.env
+   ```
+
+3. **Never type tokens into AI chat**
+   - Always edit config files directly in your editor
+   - The `/initial-setup` wizard respects this
+
+4. **Rotate tokens periodically**
+   - Every 6-12 months
+   - Immediately if compromised
+
+5. **Minimum permissions**
+   - Only grant required token permissions
+   - Use separate tokens for different environments

docs/DEBUGGING-CHECKLIST.md

@@ -0,0 +1,213 @@
+# Debugging Checklist for Marketplace Troubleshooting
+
+**Purpose:** Systematic approach to diagnose and fix plugin loading issues.
+
+Last Updated: 2026-01-22
+
+---
+
+## Step 1: Identify the Loading Path
+
+Claude Code loads plugins from different locations depending on context:
+
+| Location | Path | When Used |
+|----------|------|-----------|
+| **Source** | `~/claude-plugins-work/` | When developing in this directory |
+| **Installed** | `~/.claude/plugins/marketplaces/leo-claude-mktplace/` | After marketplace install |
+| **Cache** | `~/.claude/` | Plugin metadata, settings |
+
+**Determine which path Claude is using:**
+
+```bash
+# Check if installed marketplace exists
+ls -la ~/.claude/plugins/marketplaces/leo-claude-mktplace/
+
+# Check Claude's current plugin loading
+cat ~/.claude/settings.local.json | grep -A5 "mcpServers"
+```
+
+**Key insight:** If you're editing source but Claude uses installed, your changes won't take effect.
+
+---
+
+## Step 2: Verify Files Exist at Runtime Location
+
+Check the files Claude will actually load:
+
+```bash
+# For installed marketplace
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check MCP server exists
+ls -la $RUNTIME/mcp-servers/gitea/
+ls -la $RUNTIME/mcp-servers/netbox/
+
+# Check plugin manifests
+ls -la $RUNTIME/plugins/projman/.claude-plugin/plugin.json
+ls -la $RUNTIME/plugins/pr-review/.claude-plugin/plugin.json
+
+# Check .mcp.json files
+cat $RUNTIME/plugins/projman/.mcp.json
+```
+
+---
+
+## Step 3: Verify Virtual Environments Exist
+
+**This is the most common failure point after installation.**
+
+MCP servers require Python venvs to exist at the INSTALLED location:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check venvs exist
+ls -la $RUNTIME/mcp-servers/gitea/.venv/bin/python
+ls -la $RUNTIME/mcp-servers/netbox/.venv/bin/python
+
+# If missing, create them:
+cd $RUNTIME && ./scripts/setup.sh
+```
+
+**Common error:** "X MCP servers failed to start" = venvs don't exist in installed path.
+
+---
+
+## Step 4: Verify Symlink Resolution
+
+Plugins use symlinks to shared MCP servers. Verify they resolve correctly:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Check symlinks exist and resolve
+readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea
+readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea
+readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox
+
+# Should resolve to:
+# $RUNTIME/mcp-servers/gitea
+# $RUNTIME/mcp-servers/netbox
+```
+
+**If broken:** Symlinks are relative. If directory structure differs, they'll break.
+
+---
+
+## Step 5: Test MCP Server Startup
+
+Manually test if the MCP server can start:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# Test Gitea MCP
+cd $RUNTIME/mcp-servers/gitea
+PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')"
+
+# Test NetBox MCP
+cd $RUNTIME/mcp-servers/netbox
+PYTHONPATH=. .venv/bin/python -c "from mcp_server.server import main; print('OK')"
+```
+
+**If import fails:** Check requirements.txt installed, check Python version compatibility.
+
+---
+
+## Step 6: Verify Configuration Files
+
+Check environment variables are set:
+
+```bash
+# System-level credentials (should exist)
+cat ~/.config/claude/gitea.env
+# Should contain: GITEA_API_URL, GITEA_API_TOKEN
+
+cat ~/.config/claude/netbox.env
+# Should contain: NETBOX_API_URL, NETBOX_API_TOKEN
+
+# Project-level config (in target project)
+cat /path/to/project/.env
+# Should contain: GITEA_ORG, GITEA_REPO
+```
+
+---
+
+## Step 7: Verify Hooks Configuration
+
+Check hooks are valid:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+# List all hooks.json files
+find $RUNTIME/plugins -name "hooks.json" -exec echo "=== {} ===" \; -exec cat {} \;
+
+# Verify hook events are valid
+# Valid: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd,
+#        Notification, Stop, SubagentStop, PreCompact
+# INVALID: task-completed, file-changed, git-commit-msg-needed
+```
+
+---
+
+## Quick Diagnostic Commands
+
+Run these to quickly identify issues:
+
+```bash
+RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
+
+echo "=== Installation Status ==="
+[ -d "$RUNTIME" ] && echo "Installed: YES" || echo "Installed: NO"
+
+echo -e "\n=== Virtual Environments ==="
+[ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING"
+[ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING"
+
+echo -e "\n=== Symlinks ==="
+[ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING"
+[ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING"
+[ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING"
+
+echo -e "\n=== Config Files ==="
+[ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
+[ -f ~/.config/claude/netbox.env ] && echo "netbox.env: OK" || echo "netbox.env: MISSING"
+```
+
+---
+
+## Common Issues and Fixes
+
+| Issue | Symptom | Fix |
+|-------|---------|-----|
+| Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
+| Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks |
+| Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes |
+| Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials |
+| Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) |
+
+---
+
+## After Fixing Issues
+
+1. **Restart Claude Code** - Plugins are loaded at startup
+2. **Verify fix works** - Run a simple command that uses the MCP
+3. **Document the issue** - If it's a new failure mode, add to this checklist
+
+---
+
+## Automated Diagnostics
+
+Use these commands for automated checking:
+
+- `/debug-report` - Run full diagnostics, create issue if problems found
+- `/debug-review` - Investigate existing diagnostic issues and propose fixes
+
+---
+
+## Related Documentation
+
+- `CLAUDE.md` - Installation Paths and Troubleshooting sections
+- `docs/CONFIGURATION.md` - Setup and configuration guide
+- `docs/UPDATING.md` - Update procedures

docs/UPDATING.md

@@ -1,24 +1,71 @@
-# Updating support-claude-mktplace
+# Updating Leo Claude Marketplace
 
 This guide covers how to update your local installation when new versions are released.
 
-## Quick Update
+---
+
+## ⚠️ CRITICAL: Run Setup in Installed Location
+
+When Claude Code installs a marketplace, it copies files to `~/.claude/plugins/marketplaces/` but **does NOT create Python virtual environments**. You must run setup manually after installation or update.
+
+**After installing or updating the marketplace:**
 
 ```bash
-# 1. Pull latest changes
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
-cd /path/to/support-claude-mktplace
+```
+
+This creates the required `.venv` directories for MCP servers. Without this step, **all MCP servers will fail to start**.
+
+---
+
+## Quick Update (Source Repository)
+
+```bash
+# 1. Pull latest changes to source
+cd /path/to/leo-claude-mktplace
 git pull origin main
 
-# 2. Run post-update script
+# 2. Run post-update script (updates source repo venvs)
 ./scripts/post-update.sh
+
+# 3. CRITICAL: Run setup in installed marketplace location
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
 ```
 
+**Then restart your Claude Code session** to load any changes.
+
+---
+
 ## What the Post-Update Script Does
 
-1. **Updates Python dependencies** for MCP servers
+1. **Updates Python dependencies** for MCP servers (gitea, netbox)
 2. **Shows recent changelog entries** so you know what changed
 3. **Validates your configuration** is still compatible
 
+---
+
+## After Updating: Re-run Setup if Needed
+
+### When to Re-run `/initial-setup`
+
+You typically **don't need** to re-run setup after updates. However, re-run if:
+
+- Changelog mentions **new required environment variables**
+- Changelog mentions **breaking changes** to configuration
+- MCP tools stop working after update
+
+### For Existing Projects
+
+If an update requires new project-level configuration:
+
+```
+/project-init
+```
+
+This will detect existing settings and only add what's missing.
+
+---
+
 ## Manual Steps After Update
 
 Some updates may require manual configuration changes:
@@ -29,7 +76,7 @@ If the changelog mentions new environment variables:
 
 1. Check the variable name and purpose in the changelog
 2. Add it to the appropriate config file:
-   - Gitea variables → `~/.config/claude/gitea.env`
+   - System variables → `~/.config/claude/gitea.env` or `netbox.env`
    - Project variables → `.env` in your project root
 
 ### New MCP Server Features
@@ -37,20 +84,56 @@ If the changelog mentions new environment variables:
 If a new MCP server tool is added:
 
 1. The post-update script handles dependency installation
-2. Check `plugins/projman/README.md` for usage documentation
+2. Check plugin documentation for usage
-3. New tools are available immediately after update
+3. New tools are available immediately after session restart
 
 ### Breaking Changes
 
 Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
 
-## Troubleshooting
+### Setup Script and Configuration Workflow Changes
+
+When updating, review if changes affect the setup workflow:
+
+1. **Check for setup command changes:**
+   ```bash
+   git diff HEAD~1 plugins/*/commands/initial-setup.md
+   git diff HEAD~1 plugins/*/commands/project-init.md
+   git diff HEAD~1 plugins/*/commands/project-sync.md
+   ```
+
+2. **Check for hook changes:**
+   ```bash
+   git diff HEAD~1 plugins/*/hooks/hooks.json
+   ```
+
+3. **Check for configuration structure changes:**
+   ```bash
+   git diff HEAD~1 docs/CONFIGURATION.md
+   ```
+
+**If setup commands changed:**
+- Review what's new (new validation steps, new prompts, etc.)
+- Consider re-running `/initial-setup` or `/project-init` to benefit from improvements
+- Existing configurations remain valid unless changelog notes breaking changes
+
+**If hooks changed:**
+- Restart your Claude Code session to load new hooks
+- New hooks (like SessionStart validation) activate automatically
+
+**If configuration structure changed:**
+- Check if new variables are required
+- Run `/project-sync` if repository detection logic improved
+
+---
+
+## Troubleshooting Updates
 
 ### Dependencies fail to install
 
 ```bash
 # Rebuild virtual environment
-cd plugins/projman/mcp-servers/gitea
+cd mcp-servers/gitea
 rm -rf .venv
 python3 -m venv .venv
 source .venv/bin/activate
@@ -61,14 +144,47 @@ deactivate
 ### Configuration no longer works
 
 1. Check CHANGELOG.md for breaking changes
-2. Compare your config files with updated `.env.example` (if provided)
+2. Run `/initial-setup` to re-validate and fix configuration
-3. Run `./scripts/setup.sh` to validate configuration
+3. Compare your config files with documentation in `docs/CONFIGURATION.md`
 
-### MCP server won't start
+### MCP server won't start after update
+
+**Most common cause:** Virtual environments don't exist in the installed marketplace.
+
+```bash
+# Fix: Run setup in installed location
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+If that doesn't work:
 
 1. Check Python version: `python3 --version` (requires 3.10+)
-2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv`
+2. Verify venv exists in INSTALLED location:
-3. Check logs for specific errors
+   ```bash
+   ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/.venv
+   ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/.venv
+   ```
+3. If missing, the symlinks won't resolve. Run setup.sh as shown above.
+4. Restart Claude Code session
+5. Check logs for specific errors
+
+### "X MCP servers failed" on startup
+
+This almost always means the venvs don't exist in the installed marketplace:
+
+```bash
+cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
+```
+
+Then restart Claude Code.
+
+### New commands not available
+
+1. Restart your Claude Code session
+2. Verify the plugin is still installed
+3. Check if the command requires additional setup
+
+---
 
 ## Version Pinning
 
@@ -79,15 +195,28 @@ To stay on a specific version:
 git tag
 
 # Checkout specific version
-git checkout v2.2.0
+git checkout v3.0.0
 
 # Run post-update
 ./scripts/post-update.sh
 ```
 
+---
+
+## Checking Current Version
+
+The version is displayed in the main README.md title and in `CHANGELOG.md`.
+
+```bash
+# Check version from changelog
+head -20 CHANGELOG.md
+```
+
+---
+
 ## Getting Help
 
-- Check `plugins/projman/README.md` for projman documentation
+- Check `docs/CONFIGURATION.md` for setup guide
-- Check `plugins/projman/CONFIGURATION.md` for setup guide
+- Check `docs/COMMANDS-CHEATSHEET.md` for command reference
-- Review CHANGELOG.md for recent changes
+- Review `CHANGELOG.md` for recent changes
 - Search existing issues in Gitea

mcp-servers/gitea/README.md

@@ -389,7 +389,7 @@ def list_issues(self, state='open', labels=None, repo=None):
 
 ## License
 
-MIT License - Part of the Claude Code Marketplace project.
+MIT License - Part of the Leo Claude Marketplace project.
 
 ## Related Documentation
 
@@ -406,7 +406,7 @@ For issues or questions:
 
 ---
 
-**Built for**: Claude Code Marketplace - Project Management Plugins
+**Built for**: Leo Claude Marketplace - Project Management Plugins
 **Phase**: 1 (Complete)
 **Status**: ✅ Production Ready
 **Last Updated**: 2025-01-06

mcp-servers/gitea/mcp_server/config.py

@@ -0,0 +1,227 @@
+"""
+Configuration loader for Gitea MCP Server.
+
+Implements hybrid configuration system:
+- System-level: ~/.config/claude/gitea.env (credentials)
+- Project-level: .env (repository specification)
+- Auto-detection: Falls back to git remote URL parsing
+"""
+from pathlib import Path
+from dotenv import load_dotenv
+import os
+import re
+import subprocess
+import logging
+from typing import Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class GiteaConfig:
+    """Hybrid configuration loader with mode detection"""
+
+    def __init__(self):
+        self.api_url: Optional[str] = None
+        self.api_token: Optional[str] = None
+        self.repo: Optional[str] = None
+        self.mode: str = 'project'
+
+    def load(self) -> Dict[str, Optional[str]]:
+        """
+        Load configuration from system and project levels.
+        Project-level configuration overrides system-level.
+
+        Returns:
+            Dict containing api_url, api_token, repo, mode
+
+        Raises:
+            FileNotFoundError: If system config is missing
+            ValueError: If required configuration is missing
+        """
+        # Load system config
+        system_config = Path.home() / '.config' / 'claude' / 'gitea.env'
+        if system_config.exists():
+            load_dotenv(system_config)
+            logger.info(f"Loaded system configuration from {system_config}")
+        else:
+            raise FileNotFoundError(
+                f"System config not found: {system_config}\n"
+                "Create it with: mkdir -p ~/.config/claude && "
+                "cat > ~/.config/claude/gitea.env"
+            )
+
+        # Find project directory (MCP server cwd is plugin dir, not project dir)
+        project_dir = self._find_project_directory()
+
+        # Load project config (overrides system)
+        if project_dir:
+            project_config = project_dir / '.env'
+            if project_config.exists():
+                load_dotenv(project_config, override=True)
+                logger.info(f"Loaded project configuration from {project_config}")
+
+        # Extract values
+        self.api_url = os.getenv('GITEA_API_URL')
+        self.api_token = os.getenv('GITEA_API_TOKEN')
+        self.repo = os.getenv('GITEA_REPO')  # Optional, must be owner/repo format
+
+        # Auto-detect repo from git remote if not specified
+        if not self.repo and project_dir:
+            self.repo = self._detect_repo_from_git(project_dir)
+            if self.repo:
+                logger.info(f"Auto-detected repository from git remote: {self.repo}")
+
+        # Detect mode
+        if self.repo:
+            self.mode = 'project'
+            logger.info(f"Running in project mode: {self.repo}")
+        else:
+            self.mode = 'company'
+            logger.info("Running in company-wide mode (PMO)")
+
+        # Validate required variables
+        self._validate()
+
+        return {
+            'api_url': self.api_url,
+            'api_token': self.api_token,
+            'repo': self.repo,
+            'mode': self.mode
+        }
+
+    def _validate(self) -> None:
+        """
+        Validate that required configuration is present.
+
+        Raises:
+            ValueError: If required configuration is missing
+        """
+        required = {
+            'GITEA_API_URL': self.api_url,
+            'GITEA_API_TOKEN': self.api_token
+        }
+
+        missing = [key for key, value in required.items() if not value]
+
+        if missing:
+            raise ValueError(
+                f"Missing required configuration: {', '.join(missing)}\n"
+                "Check your ~/.config/claude/gitea.env file"
+            )
+
+    def _find_project_directory(self) -> Optional[Path]:
+        """
+        Find the user's project directory.
+
+        The MCP server runs with cwd set to the plugin directory, not the
+        user's project. We need to find the actual project directory using
+        various heuristics.
+
+        Returns:
+            Path to project directory, or None if not found
+        """
+        # Strategy 1: Check CLAUDE_PROJECT_DIR environment variable
+        project_dir = os.getenv('CLAUDE_PROJECT_DIR')
+        if project_dir:
+            path = Path(project_dir)
+            if path.exists():
+                logger.info(f"Found project directory from CLAUDE_PROJECT_DIR: {path}")
+                return path
+
+        # Strategy 2: Check PWD (original working directory before cwd override)
+        pwd = os.getenv('PWD')
+        if pwd:
+            path = Path(pwd)
+            # Verify it has .git or .env (indicates a project)
+            if path.exists() and ((path / '.git').exists() or (path / '.env').exists()):
+                logger.info(f"Found project directory from PWD: {path}")
+                return path
+
+        # Strategy 3: Check current working directory
+        # This handles test scenarios and cases where cwd is actually the project
+        cwd = Path.cwd()
+        if (cwd / '.git').exists() or (cwd / '.env').exists():
+            logger.info(f"Found project directory from cwd: {cwd}")
+            return cwd
+
+        # Strategy 4: Check if GITEA_REPO is already set (user configured it)
+        # If so, we don't need to find the project directory for git detection
+        if os.getenv('GITEA_REPO'):
+            logger.debug("GITEA_REPO already set, skipping project directory detection")
+            return None
+
+        logger.debug("Could not determine project directory")
+        return None
+
+    def _detect_repo_from_git(self, project_dir: Optional[Path] = None) -> Optional[str]:
+        """
+        Auto-detect repository from git remote origin URL.
+
+        Args:
+            project_dir: Directory to run git command from (defaults to cwd)
+
+        Supports URL formats:
+        - SSH: ssh://git@host:port/owner/repo.git
+        - SSH short: git@host:owner/repo.git
+        - HTTPS: https://host/owner/repo.git
+        - HTTP: http://host/owner/repo.git
+
+        Returns:
+            Repository in 'owner/repo' format, or None if detection fails
+        """
+        try:
+            result = subprocess.run(
+                ['git', 'remote', 'get-url', 'origin'],
+                capture_output=True,
+                text=True,
+                timeout=5,
+                cwd=str(project_dir) if project_dir else None
+            )
+            if result.returncode != 0:
+                logger.debug("No git remote 'origin' found")
+                return None
+
+            url = result.stdout.strip()
+            return self._parse_git_url(url)
+
+        except subprocess.TimeoutExpired:
+            logger.warning("Git command timed out")
+            return None
+        except FileNotFoundError:
+            logger.debug("Git not available")
+            return None
+        except Exception as e:
+            logger.debug(f"Failed to detect repo from git: {e}")
+            return None
+
+    def _parse_git_url(self, url: str) -> Optional[str]:
+        """
+        Parse git URL to extract owner/repo.
+
+        Args:
+            url: Git remote URL
+
+        Returns:
+            Repository in 'owner/repo' format, or None if parsing fails
+        """
+        # Remove .git suffix if present
+        url = re.sub(r'\.git$', '', url)
+
+        # SSH format: ssh://git@host:port/owner/repo
+        ssh_match = re.match(r'ssh://[^/]+/(.+/.+)$', url)
+        if ssh_match:
+            return ssh_match.group(1)
+
+        # SSH short format: git@host:owner/repo
+        ssh_short_match = re.match(r'git@[^:]+:(.+/.+)$', url)
+        if ssh_short_match:
+            return ssh_short_match.group(1)
+
+        # HTTPS/HTTP format: https://host/owner/repo
+        http_match = re.match(r'https?://[^/]+/(.+/.+)$', url)
+        if http_match:
+            return http_match.group(1)
+
+        logger.warning(f"Could not parse git URL: {url}")
+        return None

mcp-servers/gitea/mcp_server/gitea_client.py

@@ -110,8 +110,14 @@ class GiteaClient:
 
     def _resolve_label_ids(self, label_names: List[str], owner: str, repo: str) -> List[int]:
         """Convert label names to label IDs."""
+        full_repo = f"{owner}/{repo}"
+
+        # Only fetch org labels if repo belongs to an organization
+        org_labels = []
+        if self.is_org_repo(full_repo):
             org_labels = self.get_org_labels(owner)
-        repo_labels = self.get_labels(f"{owner}/{repo}")
+
+        repo_labels = self.get_labels(full_repo)
         all_labels = org_labels + repo_labels
         label_map = {label['name']: label['id'] for label in all_labels}
         label_ids = []
@@ -548,10 +554,33 @@ class GiteaClient:
         return response.json()
 
     def is_org_repo(self, repo: Optional[str] = None) -> bool:
-        """Check if repository belongs to an organization (not a user)."""
+        """
-        info = self.get_repo_info(repo)
+        Check if repository belongs to an organization (not a user).
-        owner_type = info.get('owner', {}).get('type', '')
+
-        return owner_type.lower() == 'organization'
+        Uses the /orgs/{owner} endpoint to reliably detect organizations,
+        as the owner.type field in repo info may be null in some Gitea versions.
+        """
+        owner, _ = self._parse_repo(repo)
+        return self._is_organization(owner)
+
+    def _is_organization(self, owner: str) -> bool:
+        """
+        Check if an owner is an organization by querying the orgs endpoint.
+
+        Args:
+            owner: The owner name to check
+
+        Returns:
+            True if owner is an organization, False if user or unknown
+        """
+        url = f"{self.base_url}/orgs/{owner}"
+        try:
+            response = self.session.get(url)
+            # 200 = organization exists, 404 = not an organization (user account)
+            return response.status_code == 200
+        except Exception as e:
+            logger.warning(f"Failed to check if {owner} is organization: {e}")
+            return False
 
     def get_branch_protection(
         self,
@@ -591,3 +620,126 @@ class GiteaClient:
         response = self.session.post(url, json=data)
         response.raise_for_status()
         return response.json()
+
+    # ========================================
+    # PULL REQUEST OPERATIONS
+    # ========================================
+
+    def list_pull_requests(
+        self,
+        state: str = 'open',
+        sort: str = 'recentupdate',
+        labels: Optional[List[str]] = None,
+        repo: Optional[str] = None
+    ) -> List[Dict]:
+        """
+        List pull requests from Gitea repository.
+
+        Args:
+            state: PR state (open, closed, all)
+            sort: Sort order (oldest, recentupdate, leastupdate, mostcomment, leastcomment, priority)
+            labels: Filter by labels
+            repo: Repository in 'owner/repo' format
+
+        Returns:
+            List of pull request dictionaries
+        """
+        owner, target_repo = self._parse_repo(repo)
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls"
+        params = {'state': state, 'sort': sort}
+        if labels:
+            params['labels'] = ','.join(labels)
+        logger.info(f"Listing PRs from {owner}/{target_repo} with state={state}")
+        response = self.session.get(url, params=params)
+        response.raise_for_status()
+        return response.json()
+
+    def get_pull_request(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """Get specific pull request details."""
+        owner, target_repo = self._parse_repo(repo)
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls/{pr_number}"
+        logger.info(f"Getting PR #{pr_number} from {owner}/{target_repo}")
+        response = self.session.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    def get_pr_diff(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> str:
+        """Get the diff for a pull request."""
+        owner, target_repo = self._parse_repo(repo)
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls/{pr_number}.diff"
+        logger.info(f"Getting diff for PR #{pr_number} from {owner}/{target_repo}")
+        response = self.session.get(url)
+        response.raise_for_status()
+        return response.text
+
+    def get_pr_comments(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> List[Dict]:
+        """Get comments on a pull request (uses issue comments endpoint)."""
+        owner, target_repo = self._parse_repo(repo)
+        # PRs share comment endpoint with issues in Gitea
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/issues/{pr_number}/comments"
+        logger.info(f"Getting comments for PR #{pr_number} from {owner}/{target_repo}")
+        response = self.session.get(url)
+        response.raise_for_status()
+        return response.json()
+
+    def create_pr_review(
+        self,
+        pr_number: int,
+        body: str,
+        event: str = 'COMMENT',
+        comments: Optional[List[Dict]] = None,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Create a review on a pull request.
+
+        Args:
+            pr_number: Pull request number
+            body: Review body/summary
+            event: Review action (APPROVE, REQUEST_CHANGES, COMMENT)
+            comments: Optional list of inline comments with path, position, body
+            repo: Repository in 'owner/repo' format
+
+        Returns:
+            Created review dictionary
+        """
+        owner, target_repo = self._parse_repo(repo)
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/pulls/{pr_number}/reviews"
+        data = {
+            'body': body,
+            'event': event
+        }
+        if comments:
+            data['comments'] = comments
+        logger.info(f"Creating review on PR #{pr_number} in {owner}/{target_repo}")
+        response = self.session.post(url, json=data)
+        response.raise_for_status()
+        return response.json()
+
+    def add_pr_comment(
+        self,
+        pr_number: int,
+        body: str,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """Add a general comment to a pull request (uses issue comment endpoint)."""
+        owner, target_repo = self._parse_repo(repo)
+        # PRs share comment endpoint with issues in Gitea
+        url = f"{self.base_url}/repos/{owner}/{target_repo}/issues/{pr_number}/comments"
+        data = {'body': body}
+        logger.info(f"Adding comment to PR #{pr_number} in {owner}/{target_repo}")
+        response = self.session.post(url, json=data)
+        response.raise_for_status()
+        return response.json()

mcp-servers/gitea/mcp_server/server.py

@@ -17,6 +17,7 @@ from .tools.labels import LabelTools
 from .tools.wiki import WikiTools
 from .tools.milestones import MilestoneTools
 from .tools.dependencies import DependencyTools
+from .tools.pull_requests import PullRequestTools
 
 # Suppress noisy MCP validation warnings on stderr
 logging.basicConfig(level=logging.INFO)
@@ -37,6 +38,7 @@ class GiteaMCPServer:
         self.wiki_tools = None
         self.milestone_tools = None
         self.dependency_tools = None
+        self.pr_tools = None
 
     async def initialize(self):
         """
@@ -55,6 +57,7 @@ class GiteaMCPServer:
             self.wiki_tools = WikiTools(self.client)
             self.milestone_tools = MilestoneTools(self.client)
             self.dependency_tools = DependencyTools(self.client)
+            self.pr_tools = PullRequestTools(self.client)
 
             logger.info(f"Gitea MCP Server initialized in {self.config['mode']} mode")
         except Exception as e:
@@ -217,6 +220,10 @@ class GiteaMCPServer:
                             "context": {
                                 "type": "string",
                                 "description": "Issue title + description or sprint context"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
                             }
                         },
                         "required": ["context"]
@@ -638,6 +645,153 @@ class GiteaMCPServer:
                         },
                         "required": ["name", "color"]
                     }
+                ),
+                # Pull Request Tools
+                Tool(
+                    name="list_pull_requests",
+                    description="List pull requests from repository",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "state": {
+                                "type": "string",
+                                "enum": ["open", "closed", "all"],
+                                "default": "open",
+                                "description": "PR state filter"
+                            },
+                            "sort": {
+                                "type": "string",
+                                "enum": ["oldest", "recentupdate", "leastupdate", "mostcomment", "leastcomment", "priority"],
+                                "default": "recentupdate",
+                                "description": "Sort order"
+                            },
+                            "labels": {
+                                "type": "array",
+                                "items": {"type": "string"},
+                                "description": "Filter by labels"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        }
+                    }
+                ),
+                Tool(
+                    name="get_pull_request",
+                    description="Get specific pull request details",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "pr_number": {
+                                "type": "integer",
+                                "description": "Pull request number"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["pr_number"]
+                    }
+                ),
+                Tool(
+                    name="get_pr_diff",
+                    description="Get the diff for a pull request",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "pr_number": {
+                                "type": "integer",
+                                "description": "Pull request number"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["pr_number"]
+                    }
+                ),
+                Tool(
+                    name="get_pr_comments",
+                    description="Get comments on a pull request",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "pr_number": {
+                                "type": "integer",
+                                "description": "Pull request number"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["pr_number"]
+                    }
+                ),
+                Tool(
+                    name="create_pr_review",
+                    description="Create a review on a pull request (approve, request changes, or comment)",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "pr_number": {
+                                "type": "integer",
+                                "description": "Pull request number"
+                            },
+                            "body": {
+                                "type": "string",
+                                "description": "Review body/summary"
+                            },
+                            "event": {
+                                "type": "string",
+                                "enum": ["APPROVE", "REQUEST_CHANGES", "COMMENT"],
+                                "default": "COMMENT",
+                                "description": "Review action"
+                            },
+                            "comments": {
+                                "type": "array",
+                                "items": {
+                                    "type": "object",
+                                    "properties": {
+                                        "path": {"type": "string"},
+                                        "position": {"type": "integer"},
+                                        "body": {"type": "string"}
+                                    }
+                                },
+                                "description": "Optional inline comments"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["pr_number", "body"]
+                    }
+                ),
+                Tool(
+                    name="add_pr_comment",
+                    description="Add a general comment to a pull request",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {
+                            "pr_number": {
+                                "type": "integer",
+                                "description": "Pull request number"
+                            },
+                            "body": {
+                                "type": "string",
+                                "description": "Comment text"
+                            },
+                            "repo": {
+                                "type": "string",
+                                "description": "Repository name (owner/repo format)"
+                            }
+                        },
+                        "required": ["pr_number", "body"]
+                    }
                 )
             ]
 
@@ -726,6 +880,19 @@ class GiteaMCPServer:
                         arguments.get('description'),
                         arguments.get('repo')
                     )
+                # Pull Request tools
+                elif name == "list_pull_requests":
+                    result = await self.pr_tools.list_pull_requests(**arguments)
+                elif name == "get_pull_request":
+                    result = await self.pr_tools.get_pull_request(**arguments)
+                elif name == "get_pr_diff":
+                    result = await self.pr_tools.get_pr_diff(**arguments)
+                elif name == "get_pr_comments":
+                    result = await self.pr_tools.get_pr_comments(**arguments)
+                elif name == "create_pr_review":
+                    result = await self.pr_tools.create_pr_review(**arguments)
+                elif name == "add_pr_comment":
+                    result = await self.pr_tools.add_pr_comment(**arguments)
                 else:
                     raise ValueError(f"Unknown tool: {name}")
 

mcp-servers/gitea/mcp_server/tools/__init__.py

@@ -4,4 +4,8 @@ MCP tools for Gitea integration.
 This package provides MCP tool implementations for:
 - Issue operations (issues.py)
 - Label management (labels.py)
+- Wiki operations (wiki.py)
+- Milestone management (milestones.py)
+- Issue dependencies (dependencies.py)
+- Pull request operations (pull_requests.py)
 """

mcp-servers/gitea/mcp_server/tools/labels.py

@@ -0,0 +1,261 @@
+"""
+Label management tools for MCP server.
+
+Provides async wrappers for label operations with:
+- Label taxonomy retrieval
+- Intelligent label suggestion
+- Dynamic label detection
+"""
+import asyncio
+import logging
+import re
+from typing import List, Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class LabelTools:
+    """Async wrappers for Gitea label operations"""
+
+    def __init__(self, gitea_client):
+        """
+        Initialize label tools.
+
+        Args:
+            gitea_client: GiteaClient instance
+        """
+        self.gitea = gitea_client
+
+    async def get_labels(self, repo: Optional[str] = None) -> Dict[str, List[Dict]]:
+        """Get all labels (org + repo if org-owned, repo-only if user-owned)."""
+        loop = asyncio.get_event_loop()
+
+        target_repo = repo or self.gitea.repo
+        if not target_repo or '/' not in target_repo:
+            raise ValueError("Use 'owner/repo' format (e.g. 'org/repo-name')")
+
+        # Check if repo belongs to an organization or user
+        is_org = await loop.run_in_executor(
+            None,
+            lambda: self.gitea.is_org_repo(target_repo)
+        )
+
+        org_labels = []
+        if is_org:
+            org = target_repo.split('/')[0]
+            org_labels = await loop.run_in_executor(
+                None,
+                lambda: self.gitea.get_org_labels(org)
+            )
+
+        repo_labels = await loop.run_in_executor(
+            None,
+            lambda: self.gitea.get_labels(target_repo)
+        )
+
+        return {
+            'organization': org_labels,
+            'repository': repo_labels,
+            'total_count': len(org_labels) + len(repo_labels)
+        }
+
+    async def suggest_labels(self, context: str, repo: Optional[str] = None) -> List[str]:
+        """
+        Analyze context and suggest appropriate labels from repository's actual labels.
+
+        This method fetches actual labels from the repository and matches them
+        dynamically, supporting any label naming convention (slash, colon-space, etc.).
+
+        Args:
+            context: Issue title + description or sprint context
+            repo: Repository in 'owner/repo' format (optional, uses default if not provided)
+
+        Returns:
+            List of suggested label names that exist in the repository
+        """
+        # Fetch actual labels from repository
+        target_repo = repo or self.gitea.repo
+        if not target_repo:
+            logger.warning("No repository specified, returning empty suggestions")
+            return []
+
+        try:
+            labels_data = await self.get_labels(target_repo)
+            all_labels = labels_data.get('organization', []) + labels_data.get('repository', [])
+            label_names = [label['name'] for label in all_labels]
+        except Exception as e:
+            logger.warning(f"Failed to fetch labels: {e}. Using fallback suggestions.")
+            label_names = []
+
+        # Build label lookup for dynamic matching
+        label_lookup = self._build_label_lookup(label_names)
+
+        suggested = []
+        context_lower = context.lower()
+
+        # Type detection (exclusive - only one)
+        type_label = None
+        if any(word in context_lower for word in ['bug', 'error', 'fix', 'broken', 'crash', 'fail']):
+            type_label = self._find_label(label_lookup, 'type', 'bug')
+        elif any(word in context_lower for word in ['refactor', 'extract', 'restructure', 'architecture', 'service extraction']):
+            type_label = self._find_label(label_lookup, 'type', 'refactor')
+        elif any(word in context_lower for word in ['feature', 'add', 'implement', 'new', 'create']):
+            type_label = self._find_label(label_lookup, 'type', 'feature')
+        elif any(word in context_lower for word in ['docs', 'documentation', 'readme', 'guide']):
+            type_label = self._find_label(label_lookup, 'type', 'documentation')
+        elif any(word in context_lower for word in ['test', 'testing', 'spec', 'coverage']):
+            type_label = self._find_label(label_lookup, 'type', 'test')
+        elif any(word in context_lower for word in ['chore', 'maintenance', 'update', 'upgrade']):
+            type_label = self._find_label(label_lookup, 'type', 'chore')
+        if type_label:
+            suggested.append(type_label)
+
+        # Priority detection
+        priority_label = None
+        if any(word in context_lower for word in ['critical', 'urgent', 'blocker', 'blocking', 'emergency']):
+            priority_label = self._find_label(label_lookup, 'priority', 'critical')
+        elif any(word in context_lower for word in ['high', 'important', 'asap', 'soon']):
+            priority_label = self._find_label(label_lookup, 'priority', 'high')
+        elif any(word in context_lower for word in ['low', 'nice-to-have', 'optional', 'later']):
+            priority_label = self._find_label(label_lookup, 'priority', 'low')
+        else:
+            priority_label = self._find_label(label_lookup, 'priority', 'medium')
+        if priority_label:
+            suggested.append(priority_label)
+
+        # Complexity detection
+        complexity_label = None
+        if any(word in context_lower for word in ['simple', 'trivial', 'easy', 'quick']):
+            complexity_label = self._find_label(label_lookup, 'complexity', 'simple')
+        elif any(word in context_lower for word in ['complex', 'difficult', 'challenging', 'intricate']):
+            complexity_label = self._find_label(label_lookup, 'complexity', 'complex')
+        else:
+            complexity_label = self._find_label(label_lookup, 'complexity', 'medium')
+        if complexity_label:
+            suggested.append(complexity_label)
+
+        # Effort detection (supports both "Effort" and "Efforts" naming)
+        effort_label = None
+        if any(word in context_lower for word in ['xs', 'tiny', '1 hour', '2 hours']):
+            effort_label = self._find_label(label_lookup, 'effort', 'xs')
+        elif any(word in context_lower for word in ['small', 's ', '1 day', 'half day']):
+            effort_label = self._find_label(label_lookup, 'effort', 's')
+        elif any(word in context_lower for word in ['medium', 'm ', '2 days', '3 days']):
+            effort_label = self._find_label(label_lookup, 'effort', 'm')
+        elif any(word in context_lower for word in ['large', 'l ', '1 week', '5 days']):
+            effort_label = self._find_label(label_lookup, 'effort', 'l')
+        elif any(word in context_lower for word in ['xl', 'extra large', '2 weeks', 'sprint']):
+            effort_label = self._find_label(label_lookup, 'effort', 'xl')
+        if effort_label:
+            suggested.append(effort_label)
+
+        # Component detection (based on keywords)
+        component_mappings = {
+            'backend': ['backend', 'server', 'api', 'database', 'service'],
+            'frontend': ['frontend', 'ui', 'interface', 'react', 'vue', 'component'],
+            'api': ['api', 'endpoint', 'rest', 'graphql', 'route'],
+            'database': ['database', 'db', 'sql', 'migration', 'schema', 'postgres'],
+            'auth': ['auth', 'authentication', 'login', 'oauth', 'token', 'session'],
+            'deploy': ['deploy', 'deployment', 'docker', 'kubernetes', 'ci/cd'],
+            'testing': ['test', 'testing', 'spec', 'jest', 'pytest', 'coverage'],
+            'docs': ['docs', 'documentation', 'readme', 'guide', 'wiki']
+        }
+
+        for component, keywords in component_mappings.items():
+            if any(keyword in context_lower for keyword in keywords):
+                label = self._find_label(label_lookup, 'component', component)
+                if label and label not in suggested:
+                    suggested.append(label)
+
+        # Tech stack detection
+        tech_mappings = {
+            'python': ['python', 'fastapi', 'django', 'flask', 'pytest'],
+            'javascript': ['javascript', 'js', 'node', 'npm', 'yarn'],
+            'docker': ['docker', 'dockerfile', 'container', 'compose'],
+            'postgresql': ['postgres', 'postgresql', 'psql', 'sql'],
+            'redis': ['redis', 'cache', 'session store'],
+            'vue': ['vue', 'vuejs', 'nuxt'],
+            'fastapi': ['fastapi', 'pydantic', 'starlette']
+        }
+
+        for tech, keywords in tech_mappings.items():
+            if any(keyword in context_lower for keyword in keywords):
+                label = self._find_label(label_lookup, 'tech', tech)
+                if label and label not in suggested:
+                    suggested.append(label)
+
+        # Source detection (based on git branch or context)
+        source_label = None
+        if 'development' in context_lower or 'dev/' in context_lower:
+            source_label = self._find_label(label_lookup, 'source', 'development')
+        elif 'staging' in context_lower or 'stage/' in context_lower:
+            source_label = self._find_label(label_lookup, 'source', 'staging')
+        elif 'production' in context_lower or 'prod' in context_lower:
+            source_label = self._find_label(label_lookup, 'source', 'production')
+        if source_label:
+            suggested.append(source_label)
+
+        # Risk detection
+        risk_label = None
+        if any(word in context_lower for word in ['breaking', 'breaking change', 'major', 'risky']):
+            risk_label = self._find_label(label_lookup, 'risk', 'high')
+        elif any(word in context_lower for word in ['safe', 'low risk', 'minor']):
+            risk_label = self._find_label(label_lookup, 'risk', 'low')
+        if risk_label:
+            suggested.append(risk_label)
+
+        logger.info(f"Suggested {len(suggested)} labels based on context and {len(label_names)} available labels")
+        return suggested
+
+    def _build_label_lookup(self, label_names: List[str]) -> Dict[str, Dict[str, str]]:
+        """
+        Build a lookup dictionary for label matching.
+
+        Supports various label formats:
+        - Slash format: Type/Bug, Priority/High
+        - Colon-space format: Type: Bug, Priority: High
+        - Colon format: Type:Bug
+
+        Args:
+            label_names: List of actual label names from repository
+
+        Returns:
+            Nested dict: {category: {value: actual_label_name}}
+        """
+        lookup: Dict[str, Dict[str, str]] = {}
+
+        for label in label_names:
+            # Try different separator patterns
+            # Pattern: Category<separator>Value
+            # Separators: /, : , :
+            match = re.match(r'^([^/:]+)(?:/|:\s*|:)(.+)$', label)
+            if match:
+                category = match.group(1).lower().rstrip('s')  # Normalize: "Efforts" -> "effort"
+                value = match.group(2).lower()
+
+                if category not in lookup:
+                    lookup[category] = {}
+                lookup[category][value] = label
+
+        return lookup
+
+    def _find_label(self, lookup: Dict[str, Dict[str, str]], category: str, value: str) -> Optional[str]:
+        """
+        Find actual label name from lookup.
+
+        Args:
+            lookup: Label lookup dictionary
+            category: Category to search (e.g., 'type', 'priority')
+            value: Value to find (e.g., 'bug', 'high')
+
+        Returns:
+            Actual label name if found, None otherwise
+        """
+        category_lower = category.lower().rstrip('s')  # Normalize
+        value_lower = value.lower()
+
+        if category_lower in lookup and value_lower in lookup[category_lower]:
+            return lookup[category_lower][value_lower]
+
+        return None

mcp-servers/gitea/mcp_server/tools/pull_requests.py

@@ -0,0 +1,274 @@
+"""
+Pull request management tools for MCP server.
+
+Provides async wrappers for PR operations with:
+- Branch-aware security
+- PMO multi-repo support
+- Comprehensive error handling
+"""
+import asyncio
+import subprocess
+import logging
+from typing import List, Dict, Optional
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class PullRequestTools:
+    """Async wrappers for Gitea pull request operations with branch detection"""
+
+    def __init__(self, gitea_client):
+        """
+        Initialize pull request tools.
+
+        Args:
+            gitea_client: GiteaClient instance
+        """
+        self.gitea = gitea_client
+
+    def _get_current_branch(self) -> str:
+        """
+        Get current git branch.
+
+        Returns:
+            Current branch name or 'unknown' if not in a git repo
+        """
+        try:
+            result = subprocess.run(
+                ['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
+                capture_output=True,
+                text=True,
+                check=True
+            )
+            return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            return "unknown"
+
+    def _check_branch_permissions(self, operation: str) -> bool:
+        """
+        Check if operation is allowed on current branch.
+
+        Args:
+            operation: Operation name (list_prs, create_review, etc.)
+
+        Returns:
+            True if operation is allowed, False otherwise
+        """
+        branch = self._get_current_branch()
+
+        # Read-only operations allowed everywhere
+        read_ops = ['list_pull_requests', 'get_pull_request', 'get_pr_diff', 'get_pr_comments']
+
+        # Production branches (read-only)
+        if branch in ['main', 'master'] or branch.startswith('prod/'):
+            return operation in read_ops
+
+        # Staging branches (read-only for PRs, can comment)
+        if branch == 'staging' or branch.startswith('stage/'):
+            return operation in read_ops + ['add_pr_comment']
+
+        # Development branches (full access)
+        if branch in ['development', 'develop'] or branch.startswith(('feat/', 'feature/', 'dev/')):
+            return True
+
+        # Unknown branch - be restrictive
+        return operation in read_ops
+
+    async def list_pull_requests(
+        self,
+        state: str = 'open',
+        sort: str = 'recentupdate',
+        labels: Optional[List[str]] = None,
+        repo: Optional[str] = None
+    ) -> List[Dict]:
+        """
+        List pull requests from repository (async wrapper).
+
+        Args:
+            state: PR state (open, closed, all)
+            sort: Sort order
+            labels: Filter by labels
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            List of pull request dictionaries
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('list_pull_requests'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot list PRs on branch '{branch}'. "
+                f"Switch to a development branch."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.list_pull_requests(state, sort, labels, repo)
+        )
+
+    async def get_pull_request(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Get specific pull request details (async wrapper).
+
+        Args:
+            pr_number: Pull request number
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            Pull request dictionary
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('get_pull_request'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot get PR on branch '{branch}'. "
+                f"Switch to a development branch."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.get_pull_request(pr_number, repo)
+        )
+
+    async def get_pr_diff(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> str:
+        """
+        Get pull request diff (async wrapper).
+
+        Args:
+            pr_number: Pull request number
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            Diff as string
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('get_pr_diff'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot get PR diff on branch '{branch}'. "
+                f"Switch to a development branch."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.get_pr_diff(pr_number, repo)
+        )
+
+    async def get_pr_comments(
+        self,
+        pr_number: int,
+        repo: Optional[str] = None
+    ) -> List[Dict]:
+        """
+        Get comments on a pull request (async wrapper).
+
+        Args:
+            pr_number: Pull request number
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            List of comment dictionaries
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('get_pr_comments'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot get PR comments on branch '{branch}'. "
+                f"Switch to a development branch."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.get_pr_comments(pr_number, repo)
+        )
+
+    async def create_pr_review(
+        self,
+        pr_number: int,
+        body: str,
+        event: str = 'COMMENT',
+        comments: Optional[List[Dict]] = None,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Create a review on a pull request (async wrapper with branch check).
+
+        Args:
+            pr_number: Pull request number
+            body: Review body/summary
+            event: Review action (APPROVE, REQUEST_CHANGES, COMMENT)
+            comments: Optional list of inline comments
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            Created review dictionary
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('create_pr_review'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot create PR review on branch '{branch}'. "
+                f"Switch to a development branch to review PRs."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.create_pr_review(pr_number, body, event, comments, repo)
+        )
+
+    async def add_pr_comment(
+        self,
+        pr_number: int,
+        body: str,
+        repo: Optional[str] = None
+    ) -> Dict:
+        """
+        Add a general comment to a pull request (async wrapper with branch check).
+
+        Args:
+            pr_number: Pull request number
+            body: Comment text
+            repo: Override configured repo (for PMO multi-repo)
+
+        Returns:
+            Created comment dictionary
+
+        Raises:
+            PermissionError: If operation not allowed on current branch
+        """
+        if not self._check_branch_permissions('add_pr_comment'):
+            branch = self._get_current_branch()
+            raise PermissionError(
+                f"Cannot add PR comment on branch '{branch}'. "
+                f"Switch to a development or staging branch to comment on PRs."
+            )
+
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.gitea.add_pr_comment(pr_number, body, repo)
+        )

mcp-servers/gitea/tests/test_config.py

@@ -149,3 +149,112 @@ def test_mode_detection_company(tmp_path, monkeypatch):
 
     assert result['mode'] == 'company'
     assert result['repo'] is None
+
+
+# ========================================
+# GIT URL PARSING TESTS
+# ========================================
+
+def test_parse_git_url_ssh_format():
+    """Test parsing SSH format git URL"""
+    config = GiteaConfig()
+
+    # SSH with port: ssh://git@host:port/owner/repo.git
+    url = "ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/personal-portfolio.git"
+    result = config._parse_git_url(url)
+    assert result == "personal-projects/personal-portfolio"
+
+
+def test_parse_git_url_ssh_short_format():
+    """Test parsing SSH short format git URL"""
+    config = GiteaConfig()
+
+    # SSH short: git@host:owner/repo.git
+    url = "git@github.com:owner/repo.git"
+    result = config._parse_git_url(url)
+    assert result == "owner/repo"
+
+
+def test_parse_git_url_https_format():
+    """Test parsing HTTPS format git URL"""
+    config = GiteaConfig()
+
+    # HTTPS: https://host/owner/repo.git
+    url = "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git"
+    result = config._parse_git_url(url)
+    assert result == "personal-projects/leo-claude-mktplace"
+
+
+def test_parse_git_url_http_format():
+    """Test parsing HTTP format git URL"""
+    config = GiteaConfig()
+
+    # HTTP: http://host/owner/repo.git
+    url = "http://gitea.hotserv.cloud/personal-projects/repo.git"
+    result = config._parse_git_url(url)
+    assert result == "personal-projects/repo"
+
+
+def test_parse_git_url_without_git_suffix():
+    """Test parsing git URL without .git suffix"""
+    config = GiteaConfig()
+
+    url = "https://github.com/owner/repo"
+    result = config._parse_git_url(url)
+    assert result == "owner/repo"
+
+
+def test_parse_git_url_invalid_format():
+    """Test parsing invalid git URL returns None"""
+    config = GiteaConfig()
+
+    url = "not-a-valid-url"
+    result = config._parse_git_url(url)
+    assert result is None
+
+
+def test_find_project_directory_from_env(tmp_path, monkeypatch):
+    """Test finding project directory from CLAUDE_PROJECT_DIR env var"""
+    project_dir = tmp_path / 'my-project'
+    project_dir.mkdir()
+    (project_dir / '.git').mkdir()
+
+    monkeypatch.setenv('CLAUDE_PROJECT_DIR', str(project_dir))
+
+    config = GiteaConfig()
+    result = config._find_project_directory()
+
+    assert result == project_dir
+
+
+def test_find_project_directory_from_cwd(tmp_path, monkeypatch):
+    """Test finding project directory from cwd with .env file"""
+    project_dir = tmp_path / 'project'
+    project_dir.mkdir()
+    (project_dir / '.env').write_text("GITEA_REPO=test/repo")
+
+    monkeypatch.chdir(project_dir)
+    # Clear env vars that might interfere
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('PWD', raising=False)
+
+    config = GiteaConfig()
+    result = config._find_project_directory()
+
+    assert result == project_dir
+
+
+def test_find_project_directory_none_when_no_markers(tmp_path, monkeypatch):
+    """Test returns None when no project markers found"""
+    empty_dir = tmp_path / 'empty'
+    empty_dir.mkdir()
+
+    monkeypatch.chdir(empty_dir)
+    monkeypatch.delenv('CLAUDE_PROJECT_DIR', raising=False)
+    monkeypatch.delenv('PWD', raising=False)
+    monkeypatch.delenv('GITEA_REPO', raising=False)
+
+    config = GiteaConfig()
+    result = config._find_project_directory()
+
+    assert result is None

mcp-servers/gitea/tests/test_gitea_client.py

@@ -222,3 +222,47 @@ def test_no_repo_specified_error(gitea_client):
             client.list_issues()
 
         assert "Repository not specified" in str(exc_info.value)
+
+
+# ========================================
+# ORGANIZATION DETECTION TESTS
+# ========================================
+
+def test_is_organization_true(gitea_client):
+    """Test _is_organization returns True for valid organization"""
+    mock_response = Mock()
+    mock_response.status_code = 200
+
+    with patch.object(gitea_client.session, 'get', return_value=mock_response):
+        result = gitea_client._is_organization('personal-projects')
+
+        assert result is True
+        gitea_client.session.get.assert_called_once_with(
+            'https://test.com/api/v1/orgs/personal-projects'
+        )
+
+
+def test_is_organization_false(gitea_client):
+    """Test _is_organization returns False for user account"""
+    mock_response = Mock()
+    mock_response.status_code = 404
+
+    with patch.object(gitea_client.session, 'get', return_value=mock_response):
+        result = gitea_client._is_organization('lmiranda')
+
+        assert result is False
+
+
+def test_is_org_repo_uses_orgs_endpoint(gitea_client):
+    """Test is_org_repo uses /orgs endpoint instead of owner.type"""
+    mock_response = Mock()
+    mock_response.status_code = 200
+
+    with patch.object(gitea_client.session, 'get', return_value=mock_response):
+        result = gitea_client.is_org_repo('personal-projects/repo')
+
+        assert result is True
+        # Should call /orgs/personal-projects, not /repos/.../
+        gitea_client.session.get.assert_called_once_with(
+            'https://test.com/api/v1/orgs/personal-projects'
+        )

mcp-servers/gitea/tests/test_labels.py

@@ -0,0 +1,478 @@
+"""
+Unit tests for label tools with suggestion logic.
+"""
+import pytest
+from unittest.mock import Mock, patch
+from mcp_server.tools.labels import LabelTools
+
+
+@pytest.fixture
+def mock_gitea_client():
+    """Fixture providing mocked Gitea client"""
+    client = Mock()
+    client.repo = 'test_org/test_repo'
+    client.is_org_repo = Mock(return_value=True)
+    return client
+
+
+@pytest.fixture
+def label_tools(mock_gitea_client):
+    """Fixture providing LabelTools instance"""
+    return LabelTools(mock_gitea_client)
+
+
+@pytest.mark.asyncio
+async def test_get_labels(label_tools):
+    """Test getting all labels (org + repo)"""
+    label_tools.gitea.get_org_labels = Mock(return_value=[
+        {'name': 'Type/Bug'},
+        {'name': 'Type/Feature'}
+    ])
+    label_tools.gitea.get_labels = Mock(return_value=[
+        {'name': 'Component/Backend'},
+        {'name': 'Component/Frontend'}
+    ])
+
+    result = await label_tools.get_labels()
+
+    assert len(result['organization']) == 2
+    assert len(result['repository']) == 2
+    assert result['total_count'] == 4
+
+
+# ========================================
+# LABEL LOOKUP TESTS (NEW)
+# ========================================
+
+def test_build_label_lookup_slash_format():
+    """Test building label lookup with slash format labels"""
+    mock_client = Mock()
+    mock_client.repo = 'test/repo'
+    tools = LabelTools(mock_client)
+
+    labels = ['Type/Bug', 'Type/Feature', 'Priority/High', 'Priority/Low']
+    lookup = tools._build_label_lookup(labels)
+
+    assert 'type' in lookup
+    assert 'bug' in lookup['type']
+    assert lookup['type']['bug'] == 'Type/Bug'
+    assert lookup['type']['feature'] == 'Type/Feature'
+    assert 'priority' in lookup
+    assert lookup['priority']['high'] == 'Priority/High'
+
+
+def test_build_label_lookup_colon_space_format():
+    """Test building label lookup with colon-space format labels"""
+    mock_client = Mock()
+    mock_client.repo = 'test/repo'
+    tools = LabelTools(mock_client)
+
+    labels = ['Type: Bug', 'Type: Feature', 'Priority: High', 'Effort: M']
+    lookup = tools._build_label_lookup(labels)
+
+    assert 'type' in lookup
+    assert 'bug' in lookup['type']
+    assert lookup['type']['bug'] == 'Type: Bug'
+    assert lookup['type']['feature'] == 'Type: Feature'
+    assert 'priority' in lookup
+    assert lookup['priority']['high'] == 'Priority: High'
+    # Test singular "Effort" (not "Efforts")
+    assert 'effort' in lookup
+    assert lookup['effort']['m'] == 'Effort: M'
+
+
+def test_build_label_lookup_efforts_normalization():
+    """Test that 'Efforts' is normalized to 'effort' for matching"""
+    mock_client = Mock()
+    mock_client.repo = 'test/repo'
+    tools = LabelTools(mock_client)
+
+    labels = ['Efforts/XS', 'Efforts/S', 'Efforts/M']
+    lookup = tools._build_label_lookup(labels)
+
+    # 'Efforts' should be normalized to 'effort'
+    assert 'effort' in lookup
+    assert lookup['effort']['xs'] == 'Efforts/XS'
+
+
+def test_find_label():
+    """Test finding labels from lookup"""
+    mock_client = Mock()
+    mock_client.repo = 'test/repo'
+    tools = LabelTools(mock_client)
+
+    lookup = {
+        'type': {'bug': 'Type: Bug', 'feature': 'Type: Feature'},
+        'priority': {'high': 'Priority: High', 'low': 'Priority: Low'}
+    }
+
+    assert tools._find_label(lookup, 'type', 'bug') == 'Type: Bug'
+    assert tools._find_label(lookup, 'priority', 'high') == 'Priority: High'
+    assert tools._find_label(lookup, 'type', 'nonexistent') is None
+    assert tools._find_label(lookup, 'nonexistent', 'bug') is None
+
+
+# ========================================
+# SUGGEST LABELS WITH DYNAMIC FORMAT TESTS
+# ========================================
+
+def _create_tools_with_labels(labels):
+    """Helper to create LabelTools with mocked labels"""
+    import asyncio
+    mock_client = Mock()
+    mock_client.repo = 'test/repo'
+    mock_client.is_org_repo = Mock(return_value=False)
+    mock_client.get_labels = Mock(return_value=[{'name': l} for l in labels])
+    return LabelTools(mock_client)
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_with_slash_format():
+    """Test label suggestion with slash format labels"""
+    labels = [
+        'Type/Bug', 'Type/Feature', 'Type/Refactor',
+        'Priority/Critical', 'Priority/High', 'Priority/Medium', 'Priority/Low',
+        'Complexity/Simple', 'Complexity/Medium', 'Complexity/Complex',
+        'Component/Auth'
+    ]
+    tools = _create_tools_with_labels(labels)
+
+    context = "Fix critical bug in login authentication"
+    suggestions = await tools.suggest_labels(context)
+
+    assert 'Type/Bug' in suggestions
+    assert 'Priority/Critical' in suggestions
+    assert 'Component/Auth' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_with_colon_space_format():
+    """Test label suggestion with colon-space format labels"""
+    labels = [
+        'Type: Bug', 'Type: Feature', 'Type: Refactor',
+        'Priority: Critical', 'Priority: High', 'Priority: Medium', 'Priority: Low',
+        'Complexity: Simple', 'Complexity: Medium', 'Complexity: Complex',
+        'Effort: XS', 'Effort: S', 'Effort: M', 'Effort: L', 'Effort: XL'
+    ]
+    tools = _create_tools_with_labels(labels)
+
+    context = "Fix critical bug for tiny 1 hour fix"
+    suggestions = await tools.suggest_labels(context)
+
+    # Should return colon-space format labels
+    assert 'Type: Bug' in suggestions
+    assert 'Priority: Critical' in suggestions
+    assert 'Effort: XS' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_bug():
+    """Test label suggestion for bug context"""
+    labels = [
+        'Type/Bug', 'Type/Feature',
+        'Priority/Critical', 'Priority/High', 'Priority/Medium', 'Priority/Low',
+        'Complexity/Simple', 'Complexity/Medium', 'Complexity/Complex',
+        'Component/Auth'
+    ]
+    tools = _create_tools_with_labels(labels)
+
+    context = "Fix critical bug in login authentication"
+    suggestions = await tools.suggest_labels(context)
+
+    assert 'Type/Bug' in suggestions
+    assert 'Priority/Critical' in suggestions
+    assert 'Component/Auth' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_feature():
+    """Test label suggestion for feature context"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium']
+    tools = _create_tools_with_labels(labels)
+
+    context = "Add new feature to implement user dashboard"
+    suggestions = await tools.suggest_labels(context)
+
+    assert 'Type/Feature' in suggestions
+    assert any('Priority' in label for label in suggestions)
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_refactor():
+    """Test label suggestion for refactor context"""
+    labels = ['Type/Refactor', 'Priority/Medium', 'Complexity/Medium', 'Component/Backend']
+    tools = _create_tools_with_labels(labels)
+
+    context = "Refactor architecture to extract service layer"
+    suggestions = await tools.suggest_labels(context)
+
+    assert 'Type/Refactor' in suggestions
+    assert 'Component/Backend' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_documentation():
+    """Test label suggestion for documentation context"""
+    labels = ['Type/Documentation', 'Priority/Medium', 'Complexity/Medium', 'Component/API', 'Component/Docs']
+    tools = _create_tools_with_labels(labels)
+
+    context = "Update documentation for API endpoints"
+    suggestions = await tools.suggest_labels(context)
+
+    assert 'Type/Documentation' in suggestions
+    assert 'Component/API' in suggestions or 'Component/Docs' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_priority():
+    """Test priority detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Critical', 'Priority/High', 'Priority/Medium', 'Priority/Low', 'Complexity/Medium']
+    tools = _create_tools_with_labels(labels)
+
+    # Critical priority
+    context = "Urgent blocker in production"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Priority/Critical' in suggestions
+
+    # High priority
+    context = "Important feature needed asap"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Priority/High' in suggestions
+
+    # Low priority
+    context = "Nice-to-have optional improvement"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Priority/Low' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_complexity():
+    """Test complexity detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Simple', 'Complexity/Medium', 'Complexity/Complex']
+    tools = _create_tools_with_labels(labels)
+
+    # Simple complexity
+    context = "Simple quick fix for typo"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Complexity/Simple' in suggestions
+
+    # Complex complexity
+    context = "Complex challenging architecture redesign"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Complexity/Complex' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_efforts():
+    """Test efforts detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium', 'Efforts/XS', 'Efforts/S', 'Efforts/M', 'Efforts/L', 'Efforts/XL']
+    tools = _create_tools_with_labels(labels)
+
+    # XS effort
+    context = "Tiny fix that takes 1 hour"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Efforts/XS' in suggestions
+
+    # L effort
+    context = "Large feature taking 1 week"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Efforts/L' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_components():
+    """Test component detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium', 'Component/Backend', 'Component/Frontend', 'Component/API', 'Component/Database']
+    tools = _create_tools_with_labels(labels)
+
+    # Backend component
+    context = "Update backend API service"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Component/Backend' in suggestions
+    assert 'Component/API' in suggestions
+
+    # Frontend component
+    context = "Fix frontend UI component"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Component/Frontend' in suggestions
+
+    # Database component
+    context = "Add database migration for schema"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Component/Database' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_tech_stack():
+    """Test tech stack detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium', 'Tech/Python', 'Tech/FastAPI', 'Tech/Docker', 'Tech/PostgreSQL']
+    tools = _create_tools_with_labels(labels)
+
+    # Python
+    context = "Update Python FastAPI endpoint"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Tech/Python' in suggestions
+    assert 'Tech/FastAPI' in suggestions
+
+    # Docker
+    context = "Fix Dockerfile configuration"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Tech/Docker' in suggestions
+
+    # PostgreSQL
+    context = "Optimize PostgreSQL query"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Tech/PostgreSQL' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_source():
+    """Test source detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium', 'Source/Development', 'Source/Staging', 'Source/Production']
+    tools = _create_tools_with_labels(labels)
+
+    # Development
+    context = "Issue found in development environment"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Source/Development' in suggestions
+
+    # Production
+    context = "Critical production issue"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Source/Production' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_risk():
+    """Test risk detection in suggestions"""
+    labels = ['Type/Feature', 'Priority/Medium', 'Complexity/Medium', 'Risk/High', 'Risk/Low']
+    tools = _create_tools_with_labels(labels)
+
+    # High risk
+    context = "Breaking change to major API"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Risk/High' in suggestions
+
+    # Low risk
+    context = "Safe minor update with low risk"
+    suggestions = await tools.suggest_labels(context)
+    assert 'Risk/Low' in suggestions
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_multiple_categories():
+    """Test that suggestions span multiple categories"""
+    labels = [
+        'Type/Bug', 'Type/Feature',
+        'Priority/Critical', 'Priority/Medium',
+        'Complexity/Complex', 'Complexity/Medium',
+        'Component/Backend', 'Component/API', 'Component/Auth',
+        'Tech/FastAPI', 'Tech/PostgreSQL',
+        'Source/Production'
+    ]
+    tools = _create_tools_with_labels(labels)
+
+    context = """
+    Urgent critical bug in production backend API service.
+    Need to fix broken authentication endpoint.
+    This is a complex issue requiring FastAPI and PostgreSQL expertise.
+    """
+
+    suggestions = await tools.suggest_labels(context)
+
+    # Should have Type
+    assert any('Type/' in label for label in suggestions)
+
+    # Should have Priority
+    assert any('Priority/' in label for label in suggestions)
+
+    # Should have Component
+    assert any('Component/' in label for label in suggestions)
+
+    # Should have Tech
+    assert any('Tech/' in label for label in suggestions)
+
+    # Should have Source
+    assert any('Source/' in label for label in suggestions)
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_empty_repo():
+    """Test suggestions when no repo specified and no labels available"""
+    mock_client = Mock()
+    mock_client.repo = None
+    tools = LabelTools(mock_client)
+
+    context = "Fix a bug"
+    suggestions = await tools.suggest_labels(context)
+
+    # Should return empty list when no repo
+    assert suggestions == []
+
+
+@pytest.mark.asyncio
+async def test_suggest_labels_no_matching_labels():
+    """Test suggestions return empty when no matching labels exist"""
+    labels = ['Custom/Label', 'Other/Thing']  # No standard labels
+    tools = _create_tools_with_labels(labels)
+
+    context = "Fix a bug"
+    suggestions = await tools.suggest_labels(context)
+
+    # Should return empty list since no Type/Bug or similar exists
+    assert len(suggestions) == 0
+
+
+@pytest.mark.asyncio
+async def test_get_labels_org_owned_repo():
+    """Test getting labels for organization-owned repository"""
+    mock_client = Mock()
+    mock_client.repo = 'myorg/myrepo'
+    mock_client.is_org_repo = Mock(return_value=True)
+    mock_client.get_org_labels = Mock(return_value=[
+        {'name': 'Type/Bug', 'id': 1},
+        {'name': 'Type/Feature', 'id': 2}
+    ])
+    mock_client.get_labels = Mock(return_value=[
+        {'name': 'Component/Backend', 'id': 3}
+    ])
+
+    tools = LabelTools(mock_client)
+    result = await tools.get_labels()
+
+    # Should fetch both org and repo labels
+    mock_client.is_org_repo.assert_called_once_with('myorg/myrepo')
+    mock_client.get_org_labels.assert_called_once_with('myorg')
+    mock_client.get_labels.assert_called_once_with('myorg/myrepo')
+
+    assert len(result['organization']) == 2
+    assert len(result['repository']) == 1
+    assert result['total_count'] == 3
+
+
+@pytest.mark.asyncio
+async def test_get_labels_user_owned_repo():
+    """Test getting labels for user-owned repository (no org labels)"""
+    mock_client = Mock()
+    mock_client.repo = 'lmiranda/personal-portfolio'
+    mock_client.is_org_repo = Mock(return_value=False)
+    mock_client.get_labels = Mock(return_value=[
+        {'name': 'bug', 'id': 1},
+        {'name': 'enhancement', 'id': 2}
+    ])
+
+    tools = LabelTools(mock_client)
+    result = await tools.get_labels()
+
+    # Should check if org repo
+    mock_client.is_org_repo.assert_called_once_with('lmiranda/personal-portfolio')
+
+    # Should NOT call get_org_labels for user-owned repos
+    mock_client.get_org_labels.assert_not_called()
+
+    # Should still get repo labels
+    mock_client.get_labels.assert_called_once_with('lmiranda/personal-portfolio')
+
+    assert len(result['organization']) == 0
+    assert len(result['repository']) == 2
+    assert result['total_count'] == 2

mcp-servers/netbox/README.md

@@ -294,4 +294,4 @@ logging.basicConfig(level=logging.DEBUG)
 
 ## License
 
-MIT License - Part of the Claude Code Marketplace (`support-claude-mktplace`).
+MIT License - Part of the Leo Claude Marketplace.

plugins/clarity-assist/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "clarity-assist",
+  "version": "1.0.0",
+  "description": "Prompt optimization and requirement clarification with ND-friendly accommodations",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "prompt-optimization",
+    "clarification",
+    "neurodivergent",
+    "requirements",
+    "methodology"
+  ],
+  "commands": ["./commands/"]
+}

plugins/clarity-assist/README.md

@@ -0,0 +1,99 @@
+# clarity-assist
+
+Prompt optimization and requirement clarification plugin with neurodivergent-friendly accommodations.
+
+## Overview
+
+clarity-assist helps transform vague, incomplete, or ambiguous requests into clear, actionable specifications. It uses a structured 4-D methodology (Deconstruct, Diagnose, Develop, Deliver) and ND-friendly communication patterns.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/clarify` | Full 4-D prompt optimization for complex requests |
+| `/quick-clarify` | Rapid single-pass clarification for simple requests |
+
+## Features
+
+### 4-D Methodology
+
+1. **Deconstruct** - Break down the request into components
+2. **Diagnose** - Analyze gaps and potential issues
+3. **Develop** - Gather clarifications through structured questions
+4. **Deliver** - Produce refined specification
+
+### ND-Friendly Design
+
+- **Option-based questioning** - Always provide 2-4 concrete choices
+- **Chunked questions** - Ask 1-2 questions at a time
+- **Context for questions** - Explain why you're asking
+- **Conflict detection** - Check previous answers before new questions
+- **Progress acknowledgment** - Summarize frequently
+
+### Escalation Protocol
+
+When requests are complex or users seem overwhelmed:
+- Acknowledge complexity
+- Offer to focus on one aspect at a time
+- Build incrementally
+
+## Installation
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["clarity-assist"]
+}
+```
+
+## Usage
+
+### Full Clarification
+
+```
+/clarify
+
+[Your vague or complex request here]
+```
+
+### Quick Clarification
+
+```
+/quick-clarify
+
+[Your mostly-clear request here]
+```
+
+## Configuration
+
+No configuration required. The plugin uses sensible defaults.
+
+## Output Format
+
+After clarification, you receive a structured specification:
+
+```markdown
+## Clarified Request
+
+### Summary
+[Description of what will be built]
+
+### Scope
+**In Scope:** [items]
+**Out of Scope:** [items]
+
+### Requirements
+[Prioritized table]
+
+### Assumptions
+[List of assumptions]
+```
+
+## Integration
+
+For CLAUDE.md integration instructions, see `claude-md-integration.md`.
+
+## License
+
+MIT

plugins/clarity-assist/agents/clarity-coach.md

@@ -0,0 +1,140 @@
+# Clarity Coach Agent
+
+## Role
+
+You are a patient, structured coach specializing in helping users articulate their requirements clearly. You are trained in neurodivergent-friendly communication patterns and use evidence-based techniques for effective requirement gathering.
+
+## Core Principles
+
+### 1. Never Open-Ended Questions Alone
+
+Bad: "What do you want the button to do?"
+Good: "What should happen when the button is clicked?
+1. Navigate to another page
+2. Submit a form
+3. Open a modal/popup
+4. Other (please describe)"
+
+### 2. Chunked Questions (1-2 at a Time)
+
+Bad: "What color, size, position, and behavior should the button have?"
+Good: "Let's start with the basics. Where should this button appear?
+1. In the header
+2. In the main content area
+3. In a sidebar
+4. Floating/fixed position"
+
+Then after answer: "Now for the appearance - should it match your existing button style or stand out?"
+
+### 3. Provide Context for Questions
+
+Always explain why you're asking:
+
+"I'm asking about error handling because it affects whether we need to build a retry mechanism."
+
+### 4. Conflict Detection
+
+Before each new question, mentally review:
+- What has the user already said?
+- Does this question potentially contradict earlier answers?
+- If yes, acknowledge it: "Earlier you mentioned X, so when thinking about Y..."
+
+### 5. Progress Acknowledgment
+
+After every 2-3 questions, summarize progress:
+
+"Great, so far we've established:
+- The feature is for [X]
+- It should [Y]
+- And integrate with [Z]
+
+A couple more questions and we'll have everything we need."
+
+## Communication Style
+
+### Tone
+- Patient, never rushing
+- Validating ("That makes sense", "Good point")
+- Non-judgmental about vague initial requests
+
+### Pacing
+- Respect user's energy levels
+- Offer breaks: "This is good progress. Want to continue or pick this up later?"
+- Notice signs of overwhelm and simplify
+
+### Clarity
+- Use concrete examples, not abstract descriptions
+- Prefer "For example..." over "Consider..."
+- Visual when possible: "Picture a button in the top-right corner that..."
+
+## Handling Uncertainty
+
+When user says "I don't know":
+
+```
+"That's totally fine - let's approach it differently.
+
+If I showed you two versions:
+- Version A: [concrete description]
+- Version B: [concrete description]
+
+Which feels closer to what you're imagining? Or neither?"
+```
+
+When user is overwhelmed:
+
+```
+"There's a lot to decide here. Let me suggest we focus on just
+the [most critical aspect] for now. The other details can be
+figured out as we build. What matters most to you right now?"
+```
+
+## Output Artifacts
+
+### During Clarification
+
+Track gathered information in a mental model:
+- Requirements (explicit)
+- Preferences (implicit)
+- Constraints (technical/business)
+- Open questions
+
+### After Clarification
+
+Produce a clear specification (see /clarify command for format).
+
+## Example Session
+
+**User:** I need a dashboard
+
+**Coach:**
+
+```
+A dashboard can mean many things - let me help narrow it down.
+
+**What's the primary purpose of this dashboard?**
+1. Monitor system health/metrics
+2. View business KPIs and analytics
+3. Manage tasks or workflows
+4. Combination / Other
+
+[Knowing this helps me understand what data and visualizations you'll need]
+```
+
+**User:** Option 2, business analytics
+
+**Coach:**
+
+```
+Business analytics dashboard - got it.
+
+**Who will be using this dashboard?**
+1. Just you / personal use
+2. Your team (5-20 people)
+3. Company-wide (many departments)
+4. External clients
+
+[This affects permissions, performance requirements, and how customizable it needs to be]
+```
+
+And so on, building toward a complete picture.

plugins/clarity-assist/claude-md-integration.md

@@ -0,0 +1,58 @@
+# clarity-assist - CLAUDE.md Integration
+
+Add the following section to your project's CLAUDE.md file to enable clarity-assist.
+
+---
+
+## Prompt Clarification
+
+This project uses the clarity-assist plugin for requirement gathering.
+
+### When to Use
+
+- Complex or vague requests
+- Multi-step implementations
+- When requirements seem incomplete
+
+### Commands
+
+| Command | Use Case |
+|---------|----------|
+| `/clarify` | Full 4-D methodology for complex requests |
+| `/quick-clarify` | Rapid mode for simple disambiguation |
+
+### Communication Style
+
+When gathering requirements:
+- Present 2-4 concrete options (never open-ended alone)
+- Ask 1-2 questions at a time
+- Explain why you're asking each question
+- Check for conflicts with previous answers
+- Summarize progress frequently
+
+### Output Format
+
+After clarification, produce a structured specification:
+
+```markdown
+## Clarified Request
+
+### Summary
+[1-2 sentence description]
+
+### Scope
+**In Scope:** [items]
+**Out of Scope:** [items]
+
+### Requirements
+| # | Requirement | Priority | Notes |
+|---|-------------|----------|-------|
+| 1 | ... | Must | ... |
+
+### Assumptions
+[List made during conversation]
+```
+
+---
+
+Copy the section between the horizontal rules into your CLAUDE.md.

plugins/clarity-assist/commands/clarify.md

@@ -0,0 +1,137 @@
+# /clarify - Full Prompt Optimization
+
+## Purpose
+
+Transform vague, incomplete, or ambiguous requests into clear, actionable specifications using the 4-D methodology with neurodivergent-friendly accommodations.
+
+## When to Use
+
+- Complex multi-step requests
+- Requirements with multiple possible interpretations
+- Tasks requiring significant context gathering
+- When user seems uncertain about what they want
+
+## 4-D Methodology
+
+### Phase 1: Deconstruct
+
+Break down the user's request into components:
+
+1. **Extract explicit requirements** - What was directly stated
+2. **Identify implicit assumptions** - What seems assumed but not stated
+3. **Note ambiguities** - Points that could go multiple ways
+4. **List dependencies** - External factors that might affect implementation
+
+### Phase 2: Diagnose
+
+Analyze gaps and potential issues:
+
+1. **Missing information** - What do we need to know?
+2. **Conflicting requirements** - Do any stated goals contradict?
+3. **Scope boundaries** - What's in/out of scope?
+4. **Technical constraints** - Platform, language, architecture limits
+
+### Phase 3: Develop
+
+Gather clarifications through structured questioning:
+
+**ND-Friendly Question Rules:**
+- Present 2-4 concrete options (never open-ended alone)
+- Include "Other" for custom responses
+- Ask 1-2 questions at a time maximum
+- Provide brief context for why you're asking
+- Check for conflicts with previous answers
+
+**Example Format:**
+```
+To help me understand the scope better:
+
+**How should errors be handled?**
+1. Silent logging (user sees nothing)
+2. Toast notifications (brief, dismissible)
+3. Modal dialogs (requires user action)
+4. Other
+
+[Context: This affects both UX and how much error-handling code we need]
+```
+
+### Phase 4: Deliver
+
+Produce the refined specification:
+
+```markdown
+## Clarified Request
+
+### Summary
+[1-2 sentence description of what will be built]
+
+### Scope
+**In Scope:**
+- [Item 1]
+- [Item 2]
+
+**Out of Scope:**
+- [Item 1]
+
+### Requirements
+
+| # | Requirement | Priority | Notes |
+|---|-------------|----------|-------|
+| 1 | ... | Must | ... |
+| 2 | ... | Should | ... |
+
+### Assumptions
+- [Assumption made based on conversation]
+
+### Open Questions
+- [Any remaining ambiguities, if any]
+```
+
+## Conflict Detection
+
+Before each question, review previous answers for conflicts:
+
+```
+[Internal check]
+Previous: User said "keep it simple"
+Current question about: Adding configuration options
+Potential conflict: More options = more complexity
+→ Acknowledge: "Earlier you mentioned keeping it simple. With that in mind..."
+```
+
+## Escalation Protocol
+
+If the request is particularly messy or the user seems overwhelmed:
+
+1. Acknowledge the complexity
+2. Offer to start with just ONE aspect
+3. Build incrementally
+
+```
+"This touches a lot of areas. Rather than tackle everything at once,
+let's start with [most critical piece]. Once that's clear, we can
+add the other parts. Sound good?"
+```
+
+## Example Interaction
+
+**User:** Make the app faster
+
+**Clarify Response:**
+
+```
+Let me help clarify what kind of performance improvements you're looking for.
+
+**What type of slowness are you experiencing?**
+1. Initial page load takes too long
+2. Interactions feel sluggish (clicking, typing)
+3. API calls are slow
+4. All of the above
+5. Other
+
+[I'm asking because each has very different solutions]
+```
+
+## Output Format
+
+After gathering all necessary information, use the Deliver phase format to present the clarified specification for user confirmation.

plugins/clarity-assist/commands/quick-clarify.md

@@ -0,0 +1,84 @@
+# /quick-clarify - Rapid Clarification Mode
+
+## Purpose
+
+Single-pass clarification for requests that are mostly clear but need minor disambiguation.
+
+## When to Use
+
+- Request is fairly clear, just one or two ambiguities
+- User is in a hurry
+- Follow-up to an already-clarified request
+- Simple feature additions or bug fixes
+
+## Process
+
+### Step 1: Echo Understanding
+
+Restate what you understood in a single sentence:
+
+```
+"I understand you want [X] that does [Y]."
+```
+
+### Step 2: Quick Disambiguation
+
+If needed, ask ONE multiple-choice question:
+
+```
+**Just to confirm:** Should this [A] or [B]?
+1. [Option A with brief description]
+2. [Option B with brief description]
+3. Both
+4. Neither / Other approach
+```
+
+### Step 3: Proceed or Confirm
+
+If confident (>90%), proceed with a brief confirmation:
+
+```
+"Got it. I'll implement [X with chosen option]. Starting now."
+```
+
+If less confident, offer a micro-summary:
+
+```
+"Quick summary before I start:
+- [Key point 1]
+- [Key point 2]
+- [Assumption made]
+
+Proceed? (Or clarify anything)"
+```
+
+## Example Interaction
+
+**User:** Add a delete button to the user list
+
+**Quick-Clarify Response:**
+
+```
+I'll add a delete button to each row in the user list.
+
+**Should deletion require confirmation?**
+1. Yes - show confirmation dialog (Recommended)
+2. No - delete immediately
+3. Soft delete - mark as deleted but keep data
+
+[Asking because accidental deletions can be problematic]
+```
+
+## Escalation to Full /clarify
+
+If quick-clarify reveals complexity:
+
+```
+"This is more involved than it first appeared - there are
+several decisions to make. Want me to switch to a more
+thorough clarification process? (Just say 'yes' or 'clarify')"
+```
+
+## Output Format
+
+For quick-clarify, no formal specification document is needed. Just proceed with the task after brief confirmation, documenting assumptions inline with the work.

plugins/clarity-assist/skills/prompt-patterns/optimization-rules.md

@@ -0,0 +1,134 @@
+# Prompt Optimization Rules
+
+## Core Rules
+
+### Rule 1: Specificity Over Generality
+
+| Instead of | Use |
+|------------|-----|
+| "Make it better" | "Reduce load time to under 2 seconds" |
+| "Add some validation" | "Validate email format and require 8+ char password" |
+| "Handle errors" | "Show toast notification on API failure, log to console" |
+
+### Rule 2: Include Context
+
+Every good prompt includes:
+- **What**: The action/feature/fix needed
+- **Where**: Location in codebase or UI
+- **Why**: Purpose or problem being solved
+- **Constraints**: Technical limits, compatibility, standards
+
+### Rule 3: Define Success
+
+Specify how to know when the task is done:
+- Acceptance criteria
+- Test cases to pass
+- Behavior to verify
+
+### Rule 4: Scope Boundaries
+
+Explicitly state:
+- What IS in scope
+- What is NOT in scope
+- What MIGHT be in scope (user's call)
+
+## Anti-Patterns to Detect
+
+### Vague Requests
+
+Triggers: "improve", "fix", "update", "change", "better", "faster", "cleaner"
+
+Response: Ask for specific metrics or outcomes
+
+### Scope Creep Signals
+
+Triggers: "while you're at it", "also", "might as well", "and another thing"
+
+Response: Acknowledge, then isolate: "I'll note that for after the main task"
+
+### Assumption Gaps
+
+Triggers: References to "the" thing (which thing?), "it" (what's it?), "there" (where?)
+
+Response: Echo back specific understanding
+
+### Conflicting Requirements
+
+Triggers: "Simple but comprehensive", "Fast but thorough", "Minimal but complete"
+
+Response: Prioritize: "Which matters more: simplicity or completeness?"
+
+## Question Templates
+
+### For Unclear Purpose
+
+```
+**What problem does this solve?**
+1. [Specific problem A]
+2. [Specific problem B]
+3. Combination
+4. Different problem: ____
+```
+
+### For Missing Scope
+
+```
+**What should this include?**
+- [ ] Feature A
+- [ ] Feature B
+- [ ] Feature C
+- [ ] Other: ____
+```
+
+### For Ambiguous Behavior
+
+```
+**When [trigger event], what should happen?**
+1. [Behavior option A]
+2. [Behavior option B]
+3. Nothing (ignore)
+4. Depends on: ____
+```
+
+### For Technical Decisions
+
+```
+**Implementation approach:**
+1. [Approach A] - pros: X, cons: Y
+2. [Approach B] - pros: X, cons: Y
+3. Let me decide based on codebase
+4. Need more info about: ____
+```
+
+## Optimization Checklist
+
+Before proceeding with any task, verify:
+
+- [ ] **Specific outcome** - Can measure success
+- [ ] **Clear location** - Know where changes go
+- [ ] **Defined scope** - Know what's in/out
+- [ ] **Error handling** - Know what happens on failure
+- [ ] **Edge cases** - Major scenarios covered
+- [ ] **Dependencies** - Know what this affects/relies on
+
+## ND-Friendly Adaptations
+
+### Reduce Cognitive Load
+- Maximum 4 options per question
+- Always include "Other" escape hatch
+- Provide examples, not just descriptions
+
+### Support Working Memory
+- Summarize frequently
+- Reference earlier decisions explicitly
+- Don't assume user remembers context
+
+### Allow Processing Time
+- Don't rapid-fire questions
+- Validate answers before moving on
+- Offer to revisit/change earlier answers
+
+### Manage Overwhelm
+- Offer to break into smaller sessions
+- Prioritize must-haves vs nice-to-haves
+- Provide "good enough for now" options

plugins/claude-config-maintainer/.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": [
     "claude-code",
@@ -16,7 +16,5 @@
     "claude-md",
     "developer-tools"
   ],
-  "entryPoint": "agents/maintainer.md",
+  "commands": ["./commands/"]
-  "commands": ["./commands/"],
-  "agents": ["./agents/"]
 }

plugins/claude-config-maintainer/README.md

@@ -12,7 +12,7 @@ CLAUDE.md files provide instructions to Claude Code when working with a project.
 
 ## Installation
 
-This plugin is part of the support-claude-mktplace collection. Install the marketplace and the plugin will be available.
+This plugin is part of the Leo Claude Marketplace. Install the marketplace and the plugin will be available.
 
 ## Commands
 
@@ -96,4 +96,4 @@ Target score: **70+** for effective Claude Code usage.
 
 ## Contributing
 
-This plugin is part of the personal-projects/support-claude-mktplace repository.
+This plugin is part of the personal-projects/leo-claude-mktplace repository.

plugins/cmdb-assistant/.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": [
     "netbox",
@@ -18,6 +18,5 @@
     "dcim"
   ],
   "commands": ["./commands/"],
-  "agents": ["./agents/"],
+  "mcpServers": ["./.mcp.json"]
-  "mcpServers": "./.mcp.json"
 }

plugins/cmdb-assistant/README.md

@@ -167,4 +167,4 @@ The plugin uses the shared NetBox MCP server at `../mcp-servers/netbox/`.
 
 ## License
 
-MIT License - Part of the Claude Code Marketplace.
+MIT License - Part of the Leo Claude Marketplace.

plugins/cmdb-assistant/commands/initial-setup.md

@@ -0,0 +1,160 @@
+---
+description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server
+---
+
+# CMDB Assistant Setup Wizard
+
+This command sets up the cmdb-assistant plugin with NetBox integration.
+
+## Important Context
+
+- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
+- **MCP tools won't work until after setup + session restart**
+- **Uses NetBox MCP server (separate from Gitea MCP)**
+
+---
+
+## Phase 1: Environment Validation
+
+### Step 1.1: Check Python Version
+
+```bash
+python3 --version
+```
+
+If below 3.10, stop setup and inform user.
+
+---
+
+## Phase 2: MCP Server Setup
+
+### Step 2.1: Locate NetBox MCP Server
+
+```bash
+find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5
+```
+
+If not found, ask user for marketplace location.
+
+### Step 2.2: Check Virtual Environment
+
+```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 server URL? (e.g., https://netbox.company.com)"
+- Header: "NetBox URL"
+- Options:
+  - "Other (I'll provide the URL)"
+
+Ask user to provide the URL.
+
+### 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/api/"
+```
+
+Report result:
+- 200: Success
+- 403: Invalid token
+- Other: Connection issue
+
+### Step 4.2: Summary
+
+```
+╔════════════════════════════════════════════════════════════╗
+║              CMDB-ASSISTANT SETUP COMPLETE                 ║
+╠════════════════════════════════════════════════════════════╣
+║ MCP Server (NetBox):   ✓ Ready                             ║
+║ System Config:         ✓ ~/.config/claude/netbox.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 `/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.

plugins/cmdb-assistant/mcp-servers/netbox

@@ -0,0 +1 @@
+../../../mcp-servers/netbox

plugins/code-sentinel/.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/code-sentinel/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": ["security", "refactoring", "code-quality", "static-analysis", "hooks"]
 }

plugins/code-sentinel/README.md

@@ -38,7 +38,7 @@ Security scanning and code refactoring tools for Claude Code projects.
 ## Installation
 
 ```bash
-/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
+/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git
 /plugin install code-sentinel
 ```
 

plugins/code-sentinel/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP, explain the issue, suggest safe alternative\n- If WARNING found: Note it briefly, proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found."
+            "prompt": "[code-sentinel] SECURITY CHECK - Before writing this code, scan for these patterns:\n\n**Critical (BLOCK if found):**\n- eval(), exec() with user input\n- SQL string concatenation (SQL injection)\n- shell=True with user input (command injection)\n- Hardcoded secrets (API keys, passwords, tokens)\n- Pickle/marshal deserialization of untrusted data\n- innerHTML/dangerouslySetInnerHTML with user content (XSS)\n\n**Warning (WARN but allow):**\n- subprocess without input validation\n- File operations without path sanitization\n- HTTP requests without timeout\n- Broad exception catches (except:)\n- Debug/print statements with sensitive data\n\n**Response:**\n- If CRITICAL found: STOP with '[code-sentinel] BLOCKED:', explain the issue, suggest safe alternative\n- If WARNING found: Note briefly with '[code-sentinel] WARNING:', proceed with suggestion\n- If clean: Proceed silently (say nothing)\n\nDo NOT announce clean scans. Only speak if issues found."
           }
         ]
       }

plugins/doc-guardian/.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/doc-guardian/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": ["documentation", "sync", "drift-detection", "automation", "hooks"]
 }

plugins/doc-guardian/README.md

@@ -11,10 +11,10 @@ Documentation gets outdated. Functions get renamed, configs change, versions bum
 
 ## Solution
 
-doc-guardian watches your code changes and automatically:
+doc-guardian monitors your code changes via hooks:
-1. Detects when changes affect documentation
+1. Detects when changes might affect documentation
-2. Queues updates silently (doesn't interrupt your flow)
+2. Alerts you to potential drift (doesn't interrupt your flow)
-3. Syncs all doc changes in a single commit when ready
+3. Provides commands to audit and sync docs when ready
 
 ## Commands
 
@@ -25,8 +25,7 @@ doc-guardian watches your code changes and automatically:
 
 ## Hooks
 
-- **PostToolUse (Write\|Edit)**: Silently checks if code changes affect docs
+- **PostToolUse (Write|Edit)**: Silently checks if code changes affect docs
-- **Stop**: Reminds you of pending doc updates before session ends
 
 ## What It Detects
 
@@ -37,10 +36,10 @@ doc-guardian watches your code changes and automatically:
 
 ## Installation
 
-This plugin is part of the claude-code-marketplace.
+This plugin is part of the Leo Claude Marketplace.
 
 ```bash
-/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git
+/plugin marketplace add https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git
 /plugin install doc-guardian
 ```
 

plugins/doc-guardian/hooks/hooks.json

@@ -6,18 +6,7 @@
         "hooks": [
           {
             "type": "prompt",
-            "prompt": "A file was just modified. Silently check if this change affects any documentation:\n\n1. If a code file changed: check if README, CLAUDE.md, docstrings, or API docs reference the modified functions/classes/configs\n2. If drift detected: add to internal queue (do NOT interrupt user flow)\n3. At natural breakpoints or when user runs /doc-sync: report pending doc updates\n\nDo NOT announce this check unless drift is found. Work silently."
+            "prompt": "[doc-guardian] QUICK drift check (DO NOT block workflow):\n\n1. ONLY check if the modified file is referenced in README.md, CLAUDE.md, or API docs in the SAME directory\n2. Do NOT read files or perform deep analysis - just note potential drift based on file name/path\n3. If potential drift: output a single line like '[doc-guardian] Note: {filename} changed - may affect {doc}. Run /doc-sync to verify.'\n4. If no obvious drift: say nothing\n\nIMPORTANT: This is notification-only. Do NOT read documentation files, do NOT make changes, do NOT use any tools. Just a quick mental check based on the file path."
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "prompt",
-            "prompt": "Before ending, check if there are pending documentation updates queued by doc-guardian. If yes, ask user: 'I detected documentation drift in X files. Run /doc-sync to update, or skip for now?'"
           }
         ]
       }

plugins/git-flow/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "git-flow",
+  "version": "1.0.0",
+  "description": "Git workflow automation with intelligent commit messages and branch management",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/git-flow/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "git",
+    "workflow",
+    "commit",
+    "branch",
+    "automation"
+  ],
+  "commands": ["./commands/"]
+}

plugins/git-flow/README.md

@@ -0,0 +1,128 @@
+# git-flow
+
+Git workflow automation with intelligent commit messages and branch management.
+
+## Overview
+
+git-flow streamlines common git operations with smart defaults, conventional commit messages, and workflow enforcement. It supports multiple branching strategies and adapts to your team's workflow.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/commit` | Create commit with auto-generated conventional message |
+| `/commit-push` | Commit and push in one operation |
+| `/commit-merge` | Commit and merge into target branch |
+| `/commit-sync` | Full sync: commit, push, and rebase on base branch |
+| `/branch-start` | Start new feature/fix/chore branch |
+| `/branch-cleanup` | Clean up merged branches |
+| `/git-status` | Enhanced status with recommendations |
+| `/git-config` | Configure git-flow settings |
+
+## Workflow Styles
+
+| Style | Description | Best For |
+|-------|-------------|----------|
+| `simple` | Direct commits to main | Solo projects |
+| `feature-branch` | Feature branches, merge when done | Small teams |
+| `pr-required` | All changes via pull request | Code review workflows |
+| `trunk-based` | Short-lived branches, frequent integration | CI/CD heavy |
+
+## Installation
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["git-flow"]
+}
+```
+
+## Configuration
+
+Set environment variables in `.env` or `~/.config/claude/git-flow.env`:
+
+```bash
+GIT_WORKFLOW_STYLE=feature-branch
+GIT_DEFAULT_BASE=development
+GIT_AUTO_DELETE_MERGED=true
+GIT_AUTO_PUSH=false
+GIT_PROTECTED_BRANCHES=main,master,development,staging
+GIT_COMMIT_STYLE=conventional
+GIT_CO_AUTHOR=true
+```
+
+Or use `/git-config` for interactive configuration.
+
+## Features
+
+### Smart Commit Messages
+
+Analyzes staged changes to generate appropriate conventional commit messages:
+
+```
+feat(auth): add password reset functionality
+
+Implement forgot password flow with email verification.
+Includes rate limiting and token expiration.
+```
+
+### Branch Naming
+
+Enforces consistent branch naming:
+
+```
+feat/add-user-authentication
+fix/login-timeout-error
+chore/update-dependencies
+```
+
+### Safety Checks
+
+- Warns before commits to protected branches
+- Confirms force push operations
+- Prevents accidental branch deletion
+
+### Conflict Resolution
+
+The git-assistant agent helps resolve merge conflicts with analysis and recommendations.
+
+## Usage Examples
+
+### Start a Feature
+
+```
+/branch-start add user authentication
+
+→ Created: feat/add-user-authentication
+  Based on: development
+```
+
+### Commit Changes
+
+```
+/commit
+
+→ Analyzing changes...
+→ Proposed: feat(auth): add login component
+→ Committed: abc1234
+```
+
+### Full Sync
+
+```
+/commit-sync
+
+→ Committed: abc1234
+→ Pushed to origin
+→ Rebased on development
+→ Status: Clean, up-to-date
+```
+
+## Integration
+
+For CLAUDE.md integration instructions, see `claude-md-integration.md`.
+
+## License
+
+MIT

plugins/git-flow/agents/git-assistant.md

@@ -0,0 +1,139 @@
+# Git Assistant Agent
+
+## Role
+
+You are a git workflow assistant that helps users navigate complex git operations, resolve conflicts, and maintain clean repository history.
+
+## Capabilities
+
+### 1. Conflict Resolution
+
+Guide users through merge conflicts:
+
+```
+Conflict detected in: src/auth/login.ts
+
+Let me analyze the conflict:
+
+<<<<<<< HEAD (your changes)
+function login(user: User) {
+  return authenticate(user.email, user.password);
+}
+=======
+function login(credentials: Credentials) {
+  return authenticate(credentials);
+}
+>>>>>>> development (incoming)
+
+Analysis:
+- Your version: Uses User type, explicit parameters
+- Their version: Uses Credentials type, single object
+
+Recommendation:
+The incoming change uses a cleaner pattern. However, you'll need
+to ensure User type is converted to Credentials.
+
+Options:
+1. Accept theirs (update your code to use Credentials)
+2. Accept yours (they'll need to adapt)
+3. Combine both (create overloaded function)
+4. Need more context about Credentials type
+```
+
+### 2. History Cleanup
+
+Help with rebasing, squashing, and amending:
+
+```
+Your branch has 15 commits, including:
+- 5 "WIP" commits
+- 3 "fix typo" commits
+- 2 "oops" commits
+
+Before merging, would you like to clean up history?
+
+Options:
+1. Squash all into single commit (cleanest)
+2. Interactive rebase (you pick what to squash)
+3. Keep as-is (preserve full history)
+```
+
+### 3. Recovery Operations
+
+Help users recover from mistakes:
+
+```
+Accidentally deleted a branch? Let's recover it:
+
+Recent deleted branches (from reflog):
+- feat/important-feature (deleted 5 mins ago)
+  Last commit: abc1234 "Add important feature"
+
+Recover this branch?
+```
+
+### 4. Complex Merges
+
+Handle cherry-picks, partial merges, octopus merges:
+
+```
+You want to merge only specific commits from feat/mixed-changes.
+
+Commits in that branch:
+1. abc1234 - Add user auth (✓ want this)
+2. def5678 - Fix unrelated bug (✗ skip)
+3. ghi9012 - Add password reset (✓ want this)
+
+I'll cherry-pick commits 1 and 3. Proceed?
+```
+
+## Communication Style
+
+### Clear Explanations
+- Explain what each command does before running
+- Show the before/after state
+- Highlight risks
+
+### Safe Defaults
+- Always prefer non-destructive operations
+- Confirm before force operations
+- Create backups before risky operations
+
+### Educational
+- Explain why conflicts occur
+- Teach patterns to avoid issues
+- Suggest workflow improvements
+
+## Safety Protocols
+
+### Before Destructive Operations
+```
+⚠️ This operation will:
+- Rewrite history for 5 commits
+- Require force push to remote
+- Affect other team members
+
+Creating backup branch: backup/feat-password-reset-20240120
+
+Proceed? (yes/no)
+```
+
+### Protected Branches
+```
+⛔ Cannot directly modify 'main' branch.
+
+This branch is protected. You should:
+1. Create a feature branch
+2. Make your changes
+3. Create a pull request
+
+Would you like me to create a branch for this change?
+```
+
+## Output Style
+
+Always show:
+- What will happen
+- Current state
+- Expected outcome
+- Recovery options if things go wrong

plugins/git-flow/claude-md-integration.md

@@ -0,0 +1,55 @@
+# git-flow - CLAUDE.md Integration
+
+Add the following section to your project's CLAUDE.md file to enable git-flow.
+
+---
+
+## Git Workflow
+
+This project uses the git-flow plugin for git operations.
+
+### Workflow Style
+
+**Style:** feature-branch
+**Base Branch:** development
+
+### Branch Naming
+
+Use the format: `<type>/<description>`
+
+Types: feat, fix, chore, docs, refactor, test, perf
+
+Examples:
+- `feat/add-user-auth`
+- `fix/login-timeout`
+- `chore/update-deps`
+
+### Commit Messages
+
+Use conventional commits:
+
+```
+<type>(<scope>): <description>
+
+[body]
+
+[footer]
+```
+
+### Commands
+
+| Command | Use Case |
+|---------|----------|
+| `/commit` | Create commit with smart message |
+| `/commit-push` | Commit and push |
+| `/commit-merge` | Commit and merge to base |
+| `/branch-start` | Start new branch |
+| `/git-status` | Enhanced status |
+
+### Protected Branches
+
+Do not commit directly to: main, development, staging
+
+---
+
+Copy the section between the horizontal rules into your CLAUDE.md.

plugins/git-flow/commands/branch-cleanup.md

@@ -0,0 +1,117 @@
+# /branch-cleanup - Clean Merged and Stale Branches
+
+## Purpose
+
+Remove branches that have been merged OR whose remote tracking branch no longer exists, both locally and optionally on remote.
+
+## Behavior
+
+### Step 1: Prune Remote Refs
+
+```bash
+# Remove stale remote-tracking references
+git fetch --prune
+```
+
+### Step 2: Identify Branches for Cleanup
+
+```bash
+# Find merged local branches
+git branch --merged <base-branch>
+
+# Find merged remote branches
+git branch -r --merged <base-branch>
+
+# Find local branches with deleted upstreams (stale)
+git branch -vv | grep ': gone]'
+```
+
+### Step 3: Present Findings
+
+```
+Found branches for cleanup:
+
+Merged (safe to delete):
+  - feat/login-page (merged 3 days ago)
+  - fix/typo-header (merged 1 week ago)
+  - chore/deps-update (merged 2 weeks ago)
+
+Stale (remote deleted):
+  - feat/old-feature (upstream gone)
+  - fix/already-merged (upstream gone)
+
+Remote (merged into base):
+  - origin/feat/login-page
+  - origin/fix/typo-header
+
+Protected (won't delete):
+  - main
+  - development
+  - staging
+
+Delete these branches?
+1. Delete all (local merged + stale + remote)
+2. Delete merged only (skip stale)
+3. Delete stale only (upstream gone)
+4. Let me pick which ones
+5. Cancel
+```
+
+### Step 4: Execute Cleanup
+
+```bash
+# Delete merged local branches
+git branch -d <branch-name>
+
+# Delete stale local branches (force needed since no upstream)
+git branch -D <stale-branch-name>
+
+# Delete remote branches
+git push origin --delete <branch-name>
+```
+
+### Step 5: Report
+
+```
+Cleanup complete:
+
+Deleted local (merged): 3 branches
+Deleted local (stale): 2 branches
+Deleted remote: 2 branches
+Skipped: 0 branches
+
+Remaining local branches:
+  - main
+  - development
+  - feat/current-work (not merged, has upstream)
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_DEFAULT_BASE` | `development` | Base branch for merge detection |
+| `GIT_PROTECTED_BRANCHES` | `main,master,development,staging,production` | Never delete these |
+| `GIT_AUTO_DELETE_REMOTE` | `false` | Auto-delete remote branches |
+| `GIT_CLEANUP_STALE` | `true` | Include stale branches (upstream gone) in cleanup |
+
+## Safety
+
+- Never deletes protected branches
+- Warns about unmerged branches that still have upstreams
+- Confirms before deleting remote branches
+- Uses `-d` (safe delete) for merged branches
+- Uses `-D` (force delete) only for stale branches with confirmation
+- Stale branches are highlighted separately for review
+
+## Output
+
+On success:
+```
+Cleaned up:
+  Local (merged): 3 branches deleted
+  Local (stale): 2 branches deleted
+  Remote: 2 branches deleted
+
+Repository is tidy!
+```

plugins/git-flow/commands/branch-start.md

@@ -0,0 +1,96 @@
+# /branch-start - Start New Branch
+
+## Purpose
+
+Create a new feature/fix/chore branch with consistent naming conventions.
+
+## Usage
+
+```
+/branch-start [description]
+```
+
+## Behavior
+
+### Step 1: Determine Branch Type
+
+```
+What type of change is this?
+1. feat - New feature
+2. fix - Bug fix
+3. chore - Maintenance task
+4. docs - Documentation
+5. refactor - Code refactoring
+```
+
+### Step 2: Get Description
+
+If not provided, ask:
+
+```
+Brief description (2-4 words):
+> add user authentication
+```
+
+### Step 3: Generate Branch Name
+
+Convert to kebab-case:
+- `feat/add-user-authentication`
+- `fix/login-timeout-error`
+- `chore/update-dependencies`
+
+### Step 4: Create Branch
+
+```bash
+# Ensure base branch is up-to-date
+git checkout <base-branch>
+git pull origin <base-branch>
+
+# Create and switch to new branch
+git checkout -b <new-branch>
+```
+
+### Step 5: Confirm
+
+```
+Created branch: feat/add-user-authentication
+Based on: development (abc1234)
+
+Ready to start coding!
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_DEFAULT_BASE` | `development` | Branch to create from |
+| `GIT_BRANCH_PREFIX` | `true` | Use type/ prefix |
+
+## Naming Rules
+
+- Lowercase only
+- Hyphens for spaces
+- No special characters
+- Max 50 characters
+
+## Validation
+
+```
+Branch name validation:
+✓ Lowercase
+✓ Valid prefix (feat/)
+✓ Descriptive (3+ words recommended)
+✗ Too long (52 chars, max 50)
+
+Suggested: feat/add-user-auth
+Use this instead? (y/n)
+```
+
+## Output
+
+On success:
+```
+Branch: feat/add-user-authentication
+Base: development @ abc1234
+Status: Ready for development
+```

plugins/git-flow/commands/commit-merge.md

@@ -0,0 +1,83 @@
+# /commit-merge - Commit and Merge
+
+## Purpose
+
+Commit current changes, then merge the current branch into a target branch.
+
+## Behavior
+
+### Step 1: Run /commit
+
+Execute the standard commit workflow.
+
+### Step 2: Identify Target Branch
+
+Check environment or ask:
+
+```
+Merge into which branch?
+1. development (Recommended - GIT_DEFAULT_BASE)
+2. main
+3. Other: ____
+```
+
+### Step 3: Merge Strategy
+
+```
+How should I merge?
+1. Merge commit (preserves history)
+2. Squash and merge (single commit)
+3. Rebase (linear history)
+```
+
+### Step 4: Execute Merge
+
+```bash
+# Switch to target
+git checkout <target>
+
+# Pull latest
+git pull origin <target>
+
+# Merge feature branch
+git merge <feature-branch> [--squash] [--no-ff]
+
+# Push
+git push origin <target>
+```
+
+### Step 5: Cleanup (Optional)
+
+```
+Merge complete. Delete the feature branch?
+1. Yes, delete local and remote (Recommended)
+2. Delete local only
+3. Keep the branch
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_DEFAULT_BASE` | `development` | Default branch to merge into |
+| `GIT_MERGE_STRATEGY` | `merge` | Default merge strategy |
+| `GIT_AUTO_DELETE_MERGED` | `true` | Auto-delete merged branches |
+
+## Safety Checks
+
+- Verify target branch exists
+- Check for uncommitted changes before switching
+- Ensure merge doesn't conflict (preview first)
+
+## Output
+
+On success:
+```
+Committed: abc1234
+feat(auth): add password reset functionality
+
+Merged feat/password-reset → development
+Deleted branch: feat/password-reset
+
+development is now at: def5678
+```

plugins/git-flow/commands/commit-push.md

@@ -0,0 +1,57 @@
+# /commit-push - Commit and Push
+
+## Purpose
+
+Create a commit and push to the remote repository in one operation.
+
+## Behavior
+
+### Step 1: Run /commit
+
+Execute the standard commit workflow (see commit.md).
+
+### Step 2: Push to Remote
+
+After successful commit:
+
+1. Check if branch has upstream tracking
+2. If no upstream, set it: `git push -u origin <branch>`
+3. If upstream exists: `git push`
+
+### Step 3: Handle Conflicts
+
+If push fails due to diverged history:
+
+```
+Remote has changes not in your local branch.
+
+Options:
+1. Pull and rebase, then push (Recommended)
+2. Pull and merge, then push
+3. Force push (⚠️ destructive)
+4. Cancel and review manually
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_AUTO_PUSH` | `true` | Auto-push after commit |
+| `GIT_PUSH_STRATEGY` | `rebase` | How to handle diverged branches |
+
+## Safety Checks
+
+- **Protected branches**: Warn before pushing to main/master/production
+- **Force push**: Require explicit confirmation
+- **No tracking**: Ask before creating new remote branch
+
+## Output
+
+On success:
+```
+Committed: abc1234
+feat(auth): add password reset functionality
+
+Pushed to: origin/feat/password-reset
+Remote URL: https://github.com/user/repo
+```

plugins/git-flow/commands/commit-sync.md

@@ -0,0 +1,104 @@
+# /commit-sync - Commit, Push, and Sync
+
+## Purpose
+
+Full sync operation: commit local changes, push to remote, sync with upstream/base branch, and clean up stale remote-tracking branches.
+
+## Behavior
+
+### Step 1: Run /commit
+
+Execute the standard commit workflow.
+
+### Step 2: Push to Remote
+
+Push committed changes to remote branch.
+
+### Step 3: Sync with Base
+
+Pull latest from base branch and rebase/merge:
+
+```bash
+# Fetch all with prune (removes stale remote-tracking refs)
+git fetch --all --prune
+
+# Rebase on base branch
+git rebase origin/<base-branch>
+
+# Push again (if rebased)
+git push --force-with-lease
+```
+
+### Step 4: Detect Stale Local Branches
+
+Check for local branches tracking deleted remotes:
+
+```bash
+# Find local branches with gone upstreams
+git branch -vv | grep ': gone]'
+```
+
+If stale branches found, report them:
+
+```
+Stale local branches (remote deleted):
+  - feat/old-feature (was tracking origin/feat/old-feature)
+  - fix/merged-bugfix (was tracking origin/fix/merged-bugfix)
+
+Run /branch-cleanup to remove these branches.
+```
+
+### Step 5: Report Status
+
+```
+Sync complete:
+
+Local:  feat/password-reset @ abc1234
+Remote: origin/feat/password-reset @ abc1234
+Base:   development @ xyz7890 (synced)
+
+Your branch is up-to-date with development.
+No conflicts detected.
+
+Cleanup:
+  Remote refs pruned: 2
+  Stale local branches: 2 (run /branch-cleanup to remove)
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_DEFAULT_BASE` | `development` | Branch to sync with |
+| `GIT_SYNC_STRATEGY` | `rebase` | How to incorporate upstream changes |
+| `GIT_AUTO_PRUNE` | `true` | Auto-prune stale remote refs on sync |
+
+## Conflict Handling
+
+If conflicts occur during rebase:
+
+```
+Conflicts detected while syncing with development.
+
+Conflicting files:
+- src/auth/login.ts
+- src/auth/types.ts
+
+Options:
+1. Open conflict resolution (I'll guide you)
+2. Abort sync (keep local state)
+3. Accept all theirs (⚠️ loses your changes in conflicts)
+4. Accept all ours (⚠️ ignores upstream in conflicts)
+```
+
+## Output
+
+On success:
+```
+Committed: abc1234
+Pushed to: origin/feat/password-reset
+Synced with: development (xyz7890)
+
+Status: Clean, up-to-date
+Stale branches: None (or N found - run /branch-cleanup)
+```

plugins/git-flow/commands/commit.md

@@ -0,0 +1,117 @@
+# /commit - Smart Commit
+
+## Purpose
+
+Create a git commit with an auto-generated conventional commit message based on staged changes.
+
+## Behavior
+
+### Step 1: Analyze Changes
+
+1. Run `git status` to see staged and unstaged changes
+2. Run `git diff --staged` to examine staged changes
+3. If nothing staged, prompt user to stage changes
+
+### Step 2: Generate Commit Message
+
+Analyze the changes and generate a conventional commit message:
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, missing semicolons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `perf`: Performance improvement
+- `test`: Adding/updating tests
+- `chore`: Maintenance tasks
+- `build`: Build system or external dependencies
+- `ci`: CI configuration
+
+**Scope:** Determined from changed files (e.g., `auth`, `api`, `ui`)
+
+### Step 3: Confirm or Edit
+
+Present the generated message:
+
+```
+Proposed commit message:
+───────────────────────
+feat(auth): add password reset functionality
+
+Implement forgot password flow with email verification.
+Includes rate limiting and token expiration.
+───────────────────────
+
+Options:
+1. Use this message (Recommended)
+2. Edit the message
+3. Regenerate with different focus
+4. Cancel
+```
+
+### Step 4: Execute Commit
+
+If confirmed, run:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<message>
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GIT_COMMIT_STYLE` | `conventional` | Message style (conventional, simple, detailed) |
+| `GIT_SIGN_COMMITS` | `false` | Use GPG signing |
+| `GIT_CO_AUTHOR` | `true` | Include Claude co-author footer |
+
+## Edge Cases
+
+### No Changes Staged
+
+```
+No changes staged for commit.
+
+Would you like to:
+1. Stage all changes (`git add -A`)
+2. Stage specific files (I'll help you choose)
+3. Cancel
+```
+
+### Untracked Files
+
+```
+Found 3 untracked files:
+- src/new-feature.ts
+- tests/new-feature.test.ts
+- docs/new-feature.md
+
+Include these in the commit?
+1. Yes, stage all (Recommended)
+2. Let me pick which ones
+3. No, commit only tracked files
+```
+
+## Output
+
+On success:
+```
+Committed: abc1234
+feat(auth): add password reset functionality
+
+Files: 3 changed, 45 insertions(+), 12 deletions(-)
+```

plugins/git-flow/commands/git-config.md

@@ -0,0 +1,100 @@
+# /git-config - Configure git-flow
+
+## Purpose
+
+Configure git-flow settings for the current project.
+
+## Behavior
+
+### Interactive Configuration
+
+```
+git-flow Configuration
+═══════════════════════════════════════════
+
+Current settings:
+  GIT_WORKFLOW_STYLE: feature-branch
+  GIT_DEFAULT_BASE: development
+  GIT_AUTO_DELETE_MERGED: true
+  GIT_AUTO_PUSH: false
+
+What would you like to configure?
+1. Workflow style
+2. Default base branch
+3. Auto-delete merged branches
+4. Auto-push after commit
+5. Protected branches
+6. View all settings
+7. Reset to defaults
+```
+
+### Setting: Workflow Style
+
+```
+Choose your workflow style:
+
+1. simple
+   - Direct commits to development
+   - No feature branches required
+   - Good for solo projects
+
+2. feature-branch (Recommended)
+   - Feature branches from development
+   - Merge when complete
+   - Good for small teams
+
+3. pr-required
+   - Feature branches from development
+   - Requires PR for merge
+   - Good for code review workflows
+
+4. trunk-based
+   - Short-lived branches
+   - Frequent integration
+   - Good for CI/CD heavy workflows
+```
+
+### Setting: Protected Branches
+
+```
+Protected branches (comma-separated):
+Current: main, master, development, staging, production
+
+These branches will:
+- Never be auto-deleted
+- Require confirmation before direct commits
+- Warn before force push
+```
+
+## Environment Variables
+
+| Variable | Default | Options |
+|----------|---------|---------|
+| `GIT_WORKFLOW_STYLE` | `feature-branch` | simple, feature-branch, pr-required, trunk-based |
+| `GIT_DEFAULT_BASE` | `development` | Any branch name |
+| `GIT_AUTO_DELETE_MERGED` | `true` | true, false |
+| `GIT_AUTO_PUSH` | `false` | true, false |
+| `GIT_PROTECTED_BRANCHES` | `main,master,development,staging,production` | Comma-separated |
+| `GIT_COMMIT_STYLE` | `conventional` | conventional, simple, detailed |
+| `GIT_CO_AUTHOR` | `true` | true, false |
+
+## Storage
+
+Settings are stored in:
+- Project: `.env` or `.claude/settings.json`
+- User: `~/.config/claude/git-flow.env`
+
+Project settings override user settings.
+
+## Output
+
+After configuration:
+```
+Configuration saved!
+
+GIT_WORKFLOW_STYLE=feature-branch
+GIT_DEFAULT_BASE=development
+GIT_AUTO_DELETE_MERGED=true
+
+These settings will be used for all git-flow commands.
+```

plugins/git-flow/commands/git-status.md

@@ -0,0 +1,72 @@
+# /git-status - Enhanced Status
+
+## Purpose
+
+Show comprehensive git status with recommendations and insights.
+
+## Behavior
+
+### Output Format
+
+```
+═══════════════════════════════════════════
+Git Status: <repo-name>
+═══════════════════════════════════════════
+
+Branch: feat/password-reset
+Base: development (3 commits ahead, 0 behind)
+Remote: origin/feat/password-reset (synced)
+
+─── Changes ───────────────────────────────
+
+Staged (ready to commit):
+  ✓ src/auth/reset.ts (modified)
+  ✓ src/auth/types.ts (modified)
+
+Unstaged:
+  • tests/auth.test.ts (modified)
+  • src/utils/email.ts (new file, untracked)
+
+─── Recommendations ───────────────────────
+
+1. Stage test file: git add tests/auth.test.ts
+2. Consider adding new file: git add src/utils/email.ts
+3. Ready to commit with 2 staged files
+
+─── Quick Actions ─────────────────────────
+
+• /commit - Commit staged changes
+• /commit-push - Commit and push
+• /commit-sync - Full sync with development
+
+═══════════════════════════════════════════
+```
+
+## Analysis Provided
+
+### Branch Health
+- Commits ahead/behind base branch
+- Sync status with remote
+- Age of branch
+
+### Change Categories
+- Staged (ready to commit)
+- Modified (not staged)
+- Untracked (new files)
+- Deleted
+- Renamed
+
+### Recommendations
+- What to stage
+- What to ignore
+- When to commit
+- When to sync
+
+### Warnings
+- Large number of changes (consider splitting)
+- Old branch (consider rebasing)
+- Conflicts with upstream
+
+## Output
+
+Always produces the formatted status report with context-aware recommendations.

plugins/git-flow/skills/workflow-patterns/branching-strategies.md

@@ -0,0 +1,183 @@
+# Git Branching Strategies
+
+## Supported Workflow Styles
+
+### 1. Simple
+
+```
+main ─────●─────●─────●─────●─────●
+          ↑     ↑     ↑     ↑     ↑
+       commit commit commit commit commit
+```
+
+**Best for:**
+- Solo projects
+- Small scripts/utilities
+- Documentation repos
+
+**Rules:**
+- Direct commits to main/development
+- No feature branches required
+- Linear history
+
+### 2. Feature Branch (Default)
+
+```
+main ─────────────────●───────────●───────────
+                      ↑           ↑
+development ────●────●────●────●────●────●────
+                ↑    ↑    ↑    ↑
+feat/a ─────●───●────┘    │    │
+                          │    │
+feat/b ──────────●────●───┘    │
+                               │
+fix/c ────────────────●────●───┘
+```
+
+**Best for:**
+- Small teams (2-5 developers)
+- Projects without formal review process
+- Rapid development cycles
+
+**Rules:**
+- Feature branches from development
+- Merge when complete
+- Delete branches after merge
+- development → main for releases
+
+### 3. PR Required
+
+```
+main ─────────────────────────────●───────────
+                                  ↑
+development ────●────●────●────●────●────●────
+                ↑    ↑    ↑    ↑
+                PR   PR   PR   PR
+                ↑    ↑    ↑    ↑
+feat/a ─────●───●    │    │    │
+                     │    │    │
+feat/b ──────────●───●    │    │
+                          │    │
+feat/c ───────────────●───●    │
+                               │
+fix/d ────────────────────●────●
+```
+
+**Best for:**
+- Teams with code review requirements
+- Open source projects
+- Projects with CI/CD gates
+
+**Rules:**
+- All changes via pull request
+- At least one approval required
+- CI must pass before merge
+- Squash commits on merge
+
+### 4. Trunk-Based
+
+```
+main ────●────●────●────●────●────●────●────●
+         ↑    ↑    ↑    ↑    ↑    ↑    ↑    ↑
+         │    │    │    │    │    │    │    │
+short branches (< 1 day)
+```
+
+**Best for:**
+- CI/CD heavy workflows
+- Experienced teams
+- High deployment frequency
+
+**Rules:**
+- Very short-lived branches (hours, not days)
+- Frequent integration to main
+- Feature flags for incomplete work
+- Continuous deployment
+
+## Branch Naming Convention
+
+```
+<type>/<description>
+```
+
+### Types
+
+| Type | Purpose | Example |
+|------|---------|---------|
+| `feat` | New feature | `feat/user-authentication` |
+| `fix` | Bug fix | `fix/login-timeout` |
+| `chore` | Maintenance | `chore/update-deps` |
+| `docs` | Documentation | `docs/api-reference` |
+| `refactor` | Code restructure | `refactor/auth-module` |
+| `test` | Test additions | `test/auth-coverage` |
+| `perf` | Performance | `perf/query-optimization` |
+
+### Naming Rules
+
+1. Lowercase only
+2. Hyphens for word separation
+3. No special characters
+4. Descriptive (2-4 words)
+5. Max 50 characters
+
+### Examples
+
+```
+✓ feat/add-password-reset
+✓ fix/null-pointer-login
+✓ chore/upgrade-typescript-5
+
+✗ Feature/Add_Password_Reset  (wrong case, underscores)
+✗ fix-bug                      (too vague)
+✗ my-branch                    (no type prefix)
+```
+
+## Protected Branches
+
+Default protected branches:
+- `main` / `master`
+- `development` / `develop`
+- `staging`
+- `production`
+
+Protection rules:
+- No direct commits
+- No force push
+- Require PR for changes
+- No deletion
+
+## Commit Message Convention
+
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Examples
+
+```
+feat(auth): add password reset flow
+
+Implement forgot password functionality with email verification.
+Includes rate limiting (5 attempts/hour) and 24h token expiration.
+
+Closes #123
+```
+
+```
+fix(ui): resolve button alignment on mobile
+
+The submit button was misaligned on screens < 768px.
+Added responsive flex rules.
+```
+
+```
+chore(deps): update dependencies
+
+- typescript 5.3 → 5.4
+- react 18.2 → 18.3
+- node 18 → 20 (LTS)
+```

plugins/pr-review/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "pr-review",
+  "version": "1.0.0",
+  "description": "Multi-agent pull request review with confidence scoring and actionable feedback",
+  "author": {
+    "name": "Leo Miranda",
+    "email": "leobmiranda@gmail.com"
+  },
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/pr-review/README.md",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
+  "license": "MIT",
+  "keywords": [
+    "pull-request",
+    "code-review",
+    "security",
+    "performance",
+    "multi-agent"
+  ],
+  "commands": ["./commands/"],
+  "mcpServers": ["./.mcp.json"]
+}

plugins/pr-review/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python",
+      "args": ["-m", "mcp_server.server"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea",
+      "env": {
+        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea"
+      }
+    }
+  }
+}

plugins/pr-review/README.md

@@ -0,0 +1,126 @@
+# pr-review
+
+Multi-agent pull request review with confidence scoring and actionable feedback.
+
+## Overview
+
+pr-review conducts comprehensive code reviews using specialized agents for security, performance, maintainability, and test coverage. Each finding includes a confidence score to reduce noise and focus on real issues.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/pr-review <pr#>` | Full multi-agent review |
+| `/pr-summary <pr#>` | Quick summary without full review |
+| `/pr-findings <pr#>` | Filter findings by category/confidence |
+
+## Review Agents
+
+| Agent | Focus |
+|-------|-------|
+| **Security Reviewer** | Injections, auth, data exposure, crypto |
+| **Performance Analyst** | N+1 queries, complexity, memory, caching |
+| **Maintainability Auditor** | Complexity, duplication, naming, coupling |
+| **Test Validator** | Coverage, test quality, flaky tests |
+
+## Confidence Scoring
+
+Findings are scored 0.0 - 1.0:
+
+| Range | Label | Action |
+|-------|-------|--------|
+| 0.9 - 1.0 | HIGH | Must address |
+| 0.7 - 0.89 | MEDIUM | Should address |
+| 0.5 - 0.69 | LOW | Consider addressing |
+| < 0.5 | (suppressed) | Not reported |
+
+## Installation
+
+Add to your project's `.claude/settings.json`:
+
+```json
+{
+  "plugins": ["pr-review"]
+}
+```
+
+Requires Gitea MCP server configuration.
+
+## Configuration
+
+```bash
+# Minimum confidence to report (default: 0.5)
+PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
+
+# Auto-submit review to Gitea (default: false)
+PR_REVIEW_AUTO_SUBMIT=false
+```
+
+## Usage Examples
+
+### Full Review
+
+```
+/pr-review 123
+
+═══════════════════════════════════════════════════
+PR Review Report: #123
+═══════════════════════════════════════════════════
+
+Summary:
+  Files changed: 12
+  Lines: +234 / -45
+
+Findings: 8 total
+  🔴 Critical: 1
+  🟠 Major: 2
+  🟡 Minor: 3
+  💡 Suggestions: 2
+
+[Detailed findings...]
+
+VERDICT: REQUEST_CHANGES
+═══════════════════════════════════════════════════
+```
+
+### Filter Findings
+
+```
+/pr-findings 123 --category security
+
+# Shows only security-related findings
+```
+
+### Quick Summary
+
+```
+/pr-summary 123
+
+# Shows change overview without full analysis
+```
+
+## Output
+
+Review reports include:
+- Summary statistics
+- Findings grouped by severity
+- Code snippets with context
+- Suggested fixes
+- Overall verdict (APPROVE/COMMENT/REQUEST_CHANGES)
+
+## Verdict Logic
+
+| Condition | Verdict |
+|-----------|---------|
+| Any critical finding | REQUEST_CHANGES |
+| 2+ major findings | REQUEST_CHANGES |
+| Only minor/suggestions | COMMENT |
+| No significant findings | APPROVE |
+
+## Integration
+
+For CLAUDE.md integration instructions, see `claude-md-integration.md`.
+
+## License
+
+MIT

plugins/pr-review/agents/coordinator.md

@@ -0,0 +1,133 @@
+# Coordinator Agent
+
+## Role
+
+You are the review coordinator that orchestrates the multi-agent PR review process. You dispatch tasks to specialized reviewers, aggregate their findings, and produce the final review report.
+
+## Responsibilities
+
+### 1. PR Analysis
+
+Before dispatching to agents:
+1. Fetch PR metadata and diff
+2. Identify changed file types
+3. Determine which agents are relevant
+
+### 2. Agent Dispatch
+
+Dispatch to appropriate agents based on changes:
+
+| File Pattern | Agents to Dispatch |
+|--------------|-------------------|
+| `*.ts`, `*.js` | Security, Performance, Maintainability |
+| `*.test.*`, `*_test.*` | Test Validator |
+| `*.sql`, `*migration*` | Security (SQL injection) |
+| `*.css`, `*.scss` | Maintainability only |
+| `*.md`, `*.txt` | Skip (documentation) |
+
+### 3. Finding Aggregation
+
+Collect findings from all agents:
+- Deduplicate similar findings
+- Merge overlapping concerns
+- Validate confidence scores
+
+### 4. Report Generation
+
+Produce structured report:
+1. Summary statistics
+2. Findings by severity (critical → suggestion)
+3. Per-finding details
+4. Overall verdict
+
+### 5. Verdict Decision
+
+Determine final verdict:
+
+| Condition | Verdict |
+|-----------|---------|
+| Any critical finding | REQUEST_CHANGES |
+| 2+ major findings | REQUEST_CHANGES |
+| Only minor/suggestions | COMMENT |
+| No significant findings | APPROVE |
+
+## Communication Protocol
+
+### To Sub-Agents
+
+```
+REVIEW_TASK:
+  pr_number: 123
+  files: [list of relevant files]
+  diff: [relevant diff sections]
+  context: [PR description, existing comments]
+
+EXPECTED_RESPONSE:
+  findings: [
+    {
+      id: string,
+      category: string,
+      severity: critical|major|minor|suggestion,
+      confidence: 0.0-1.0,
+      file: string,
+      line: number,
+      title: string,
+      description: string,
+      fix: string (optional)
+    }
+  ]
+```
+
+### Report Template
+
+```
+═══════════════════════════════════════════════════
+PR Review Report: #<number>
+═══════════════════════════════════════════════════
+
+Summary:
+  Files changed: <n>
+  Lines: +<added> / -<removed>
+  Agents consulted: <list>
+
+Findings: <total>
+  🔴 Critical: <n>
+  🟠 Major: <n>
+  🟡 Minor: <n>
+  💡 Suggestions: <n>
+
+[Findings grouped by severity]
+
+───────────────────────────────────────────────────
+VERDICT: <APPROVE|COMMENT|REQUEST_CHANGES>
+───────────────────────────────────────────────────
+
+<Justification>
+```
+
+## Behavior Guidelines
+
+### Be Decisive
+
+Provide clear verdict with justification. Don't hedge.
+
+### Prioritize Actionability
+
+Focus on findings that:
+- Have clear fixes
+- Impact security or correctness
+- Are within author's control
+
+### Respect Confidence Thresholds
+
+Never report findings below 0.5 confidence. Be transparent about uncertainty:
+- 0.9+ → "This is definitely an issue"
+- 0.7-0.89 → "This is likely an issue"
+- 0.5-0.69 → "This might be an issue"
+
+### Avoid Noise
+
+Don't report:
+- Style preferences (unless egregious)
+- Minor naming issues
+- Theoretical problems with no practical impact

plugins/pr-review/agents/maintainability-auditor.md

@@ -0,0 +1,99 @@
+# Maintainability Auditor Agent
+
+## Role
+
+You are a code quality reviewer that identifies maintainability issues, code smells, and opportunities to improve code clarity and long-term health.
+
+## Focus Areas
+
+### 1. Code Complexity
+
+- **Long Functions**: >50 lines, too many responsibilities
+- **Deep Nesting**: >3 levels of conditionals
+- **Complex Conditionals**: Hard to follow boolean logic
+- **God Objects**: Classes/modules doing too much
+
+### 2. Code Duplication
+
+- **Copy-Paste Code**: Repeated blocks that should be abstracted
+- **Similar Patterns**: Logic that could be generalized
+
+### 3. Naming & Clarity
+
+- **Unclear Names**: Variables like `x`, `data`, `temp`
+- **Misleading Names**: Names that don't match behavior
+- **Inconsistent Naming**: Mixed conventions
+
+### 4. Architecture Concerns
+
+- **Tight Coupling**: Components too interdependent
+- **Missing Abstraction**: Concrete details leaking
+- **Broken Patterns**: Violating established patterns in codebase
+
+### 5. Error Handling
+
+- **Swallowed Errors**: Empty catch blocks
+- **Generic Errors**: Losing error context
+- **Missing Error Handling**: No handling for expected failures
+
+## Finding Format
+
+```json
+{
+  "id": "MAINT-001",
+  "category": "maintainability",
+  "subcategory": "complexity",
+  "severity": "minor",
+  "confidence": 0.75,
+  "file": "src/services/orderProcessor.ts",
+  "line": 45,
+  "title": "Function Too Long",
+  "description": "The processOrder function is 120 lines with 5 distinct responsibilities: validation, pricing, inventory, notification, and logging.",
+  "impact": "Difficult to test, understand, and modify. Changes risk unintended side effects.",
+  "fix": "Extract each responsibility into a separate function: validateOrder(), calculatePricing(), updateInventory(), sendNotification(), logOrder()."
+}
+```
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Makes code dangerous to modify |
+| Major | Significantly impacts readability/maintainability |
+| Minor | Noticeable but manageable issue |
+| Suggestion | Nice to have, not blocking |
+
+## Confidence Calibration
+
+Maintainability is subjective. Be measured:
+
+HIGH confidence when:
+- Clear violation of established patterns
+- Obvious duplication or complexity
+- Measurable metrics exceed thresholds
+
+MEDIUM confidence when:
+- Judgment call on complexity
+- Could be intentional design choice
+- Depends on team conventions
+
+Suppress when:
+- Style preference not shared by team
+- Generated or third-party code
+- Temporary code with TODO
+
+## Special Considerations
+
+### Context Awareness
+
+Check existing patterns before flagging:
+- If codebase uses X pattern, don't suggest Y
+- If similar code exists elsewhere, ensure consistency
+- Respect team conventions over personal preference
+
+### Constructive Feedback
+
+Always provide:
+- Why it matters
+- Concrete improvement suggestion
+- Example if complex

plugins/pr-review/agents/performance-analyst.md

@@ -0,0 +1,93 @@
+# Performance Analyst Agent
+
+## Role
+
+You are a performance-focused code reviewer that identifies performance issues, inefficiencies, and optimization opportunities in pull request changes.
+
+## Focus Areas
+
+### 1. Database Performance
+
+- **N+1 Queries**: Loop with query inside
+- **Missing Indexes**: Queries on unindexed columns
+- **Over-fetching**: SELECT * when specific columns needed
+- **Unbounded Queries**: No LIMIT on potentially large result sets
+
+Confidence scoring:
+- Clear N+1 in loop: 0.9
+- Possible N+1 with unclear iteration: 0.7
+- Query without visible index: 0.5
+
+### 2. Algorithm Complexity
+
+- **Nested Loops**: O(n²) when O(n) possible
+- **Repeated Calculations**: Same computation in loop
+- **Inefficient Data Structures**: Array search vs Set/Map lookup
+
+### 3. Memory Issues
+
+- **Memory Leaks**: Unclosed resources, growing caches
+- **Large Allocations**: Loading entire files/datasets into memory
+- **Unnecessary Copies**: Cloning when reference would work
+
+### 4. Network/IO
+
+- **Sequential Requests**: When parallel would work
+- **Missing Caching**: Repeated fetches of same data
+- **Large Payloads**: Sending unnecessary data
+
+### 5. Frontend Performance
+
+- **Unnecessary Re-renders**: Missing memoization
+- **Large Bundle Impact**: Heavy imports
+- **Blocking Operations**: Sync ops on main thread
+
+## Finding Format
+
+```json
+{
+  "id": "PERF-001",
+  "category": "performance",
+  "subcategory": "database",
+  "severity": "major",
+  "confidence": 0.85,
+  "file": "src/services/orders.ts",
+  "line": 23,
+  "title": "N+1 Query Pattern",
+  "description": "For each order, a separate query fetches the user. With 100 orders, this executes 101 queries.",
+  "evidence": "orders.forEach(order => { const user = await db.users.find(order.userId); })",
+  "impact": "Linear increase in database load with order count. 1000 orders = 1001 queries.",
+  "fix": "Use eager loading or batch the user IDs: db.users.findMany({ id: { in: userIds } })"
+}
+```
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Will cause outage or severe degradation at scale |
+| Major | Significant impact on response time or resources |
+| Minor | Measurable but tolerable impact |
+| Suggestion | Optimization opportunity, premature if not hot path |
+
+## Confidence Calibration
+
+Be conservative about performance claims:
+- Measure or cite benchmarks when possible
+- Consider actual usage patterns
+- Acknowledge when impact depends on scale
+
+HIGH confidence when:
+- Clear algorithmic issue (N+1, O(n²))
+- Pattern known to cause problems
+- Impact calculable from code
+
+MEDIUM confidence when:
+- Depends on data size
+- Might be optimized elsewhere
+- Theoretical improvement
+
+Suppress when:
+- Likely not a hot path
+- Micro-optimization
+- Depends heavily on runtime

plugins/pr-review/agents/security-reviewer.md

@@ -0,0 +1,93 @@
+# Security Reviewer Agent
+
+## Role
+
+You are a security-focused code reviewer that identifies vulnerabilities, security anti-patterns, and potential exploits in pull request changes.
+
+## Focus Areas
+
+### 1. Injection Vulnerabilities
+
+- **SQL Injection**: String concatenation in queries
+- **Command Injection**: Unescaped user input in shell commands
+- **XSS**: Unescaped output in HTML/templates
+- **LDAP/XML Injection**: Similar patterns in other contexts
+
+Confidence scoring:
+- Direct user input → query string: 0.95
+- Indirect path with possible taint: 0.7
+- Theoretical with no clear path: 0.4
+
+### 2. Authentication & Authorization
+
+- Missing auth checks on endpoints
+- Hardcoded credentials
+- Weak password policies
+- Session management issues
+- JWT vulnerabilities (weak signing, no expiration)
+
+### 3. Data Exposure
+
+- Sensitive data in logs
+- Unencrypted sensitive storage
+- Excessive data in API responses
+- Missing field-level permissions
+
+### 4. Input Validation
+
+- Missing validation on user input
+- Type coercion vulnerabilities
+- Path traversal possibilities
+- File upload without validation
+
+### 5. Cryptography
+
+- Weak algorithms (MD5, SHA1 for passwords)
+- Hardcoded keys/IVs
+- Predictable random values
+- Missing salt
+
+## Finding Format
+
+```json
+{
+  "id": "SEC-001",
+  "category": "security",
+  "subcategory": "injection",
+  "severity": "critical",
+  "confidence": 0.95,
+  "file": "src/api/users.ts",
+  "line": 45,
+  "title": "SQL Injection Vulnerability",
+  "description": "User-provided 'id' parameter is directly interpolated into SQL query without parameterization.",
+  "evidence": "const query = `SELECT * FROM users WHERE id = ${userId}`;",
+  "impact": "Attacker can read, modify, or delete any data in the database.",
+  "fix": "Use parameterized queries: db.query('SELECT * FROM users WHERE id = ?', [userId])"
+}
+```
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Exploitable with high impact (data breach, RCE) |
+| Major | Exploitable with moderate impact, or high impact requiring specific conditions |
+| Minor | Low impact or requires unlikely conditions |
+| Suggestion | Best practice, defense in depth |
+
+## Confidence Calibration
+
+Be conservative. Only report HIGH confidence when:
+- Clear data flow from untrusted source to sink
+- No intervening validation visible
+- Pattern matches known vulnerability
+
+Report MEDIUM confidence when:
+- Pattern looks suspicious but context unclear
+- Validation might exist elsewhere
+- Depends on configuration
+
+Suppress (< 0.5) when:
+- Purely theoretical
+- Would require multiple unlikely conditions
+- Pattern is common but safe in context

plugins/pr-review/agents/test-validator.md

@@ -0,0 +1,110 @@
+# Test Validator Agent
+
+## Role
+
+You are a test quality reviewer that validates test coverage, test quality, and testing practices in pull request changes.
+
+## Focus Areas
+
+### 1. Coverage Gaps
+
+- **Untested Code**: New functions without corresponding tests
+- **Missing Edge Cases**: Only happy path tested
+- **Uncovered Branches**: Conditionals with untested paths
+
+### 2. Test Quality
+
+- **Weak Assertions**: Tests that can't fail
+- **Test Pollution**: Tests affecting each other
+- **Flaky Patterns**: Time-dependent or order-dependent tests
+- **Mocking Overuse**: Testing mocks instead of behavior
+
+### 3. Test Structure
+
+- **Missing Arrangement**: No clear setup
+- **Unclear Act**: What's being tested isn't obvious
+- **Weak Assert**: Vague or missing assertions
+- **Missing Cleanup**: Resources not cleaned up
+
+### 4. Test Naming
+
+- **Unclear Names**: `test1`, `testFunction`
+- **Missing Scenario**: What condition is being tested
+- **Missing Expectation**: What should happen
+
+### 5. Test Maintenance
+
+- **Brittle Tests**: Break with unrelated changes
+- **Duplicate Setup**: Same setup repeated
+- **Dead Tests**: Commented out or always-skipped
+
+## Finding Format
+
+```json
+{
+  "id": "TEST-001",
+  "category": "tests",
+  "subcategory": "coverage",
+  "severity": "major",
+  "confidence": 0.8,
+  "file": "src/services/auth.ts",
+  "line": 45,
+  "title": "New Function Not Tested",
+  "description": "The new validatePassword function has no corresponding test cases. This function handles security-critical validation.",
+  "evidence": "Added validatePassword() in auth.ts, no matching test in auth.test.ts",
+  "impact": "Regression bugs in password validation may go undetected.",
+  "fix": "Add test cases for: valid password, too short, missing number, missing special char, common password rejection."
+}
+```
+
+## Severity Guidelines
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | No tests for security/critical functionality |
+| Major | Significant functionality untested |
+| Minor | Edge cases or minor paths untested |
+| Suggestion | Test quality improvement opportunity |
+
+## Confidence Calibration
+
+Test coverage is verifiable:
+
+HIGH confidence when:
+- Can verify no test file exists
+- Can see function is called but never in test
+- Pattern is clearly problematic
+
+MEDIUM confidence when:
+- Tests might exist elsewhere
+- Integration tests might cover it
+- Pattern might be intentional
+
+Suppress when:
+- Generated code
+- Simple getters/setters
+- Framework code
+
+## Test Expectations by Code Type
+
+| Code Type | Expected Tests |
+|-----------|---------------|
+| API endpoint | Happy path, error cases, auth, validation |
+| Utility function | Input variations, edge cases, errors |
+| UI component | Rendering, interactions, accessibility |
+| Database operation | CRUD, constraints, transactions |
+
+## Constructive Suggestions
+
+When flagging missing tests, suggest specific cases:
+
+```
+Missing tests for processPayment():
+
+Suggested test cases:
+1. Valid payment processes successfully
+2. Invalid card number returns error
+3. Insufficient funds handled
+4. Network timeout retries appropriately
+5. Duplicate payment prevention
+```

plugins/pr-review/claude-md-integration.md

@@ -0,0 +1,46 @@
+# pr-review - CLAUDE.md Integration
+
+Add the following section to your project's CLAUDE.md file to enable pr-review.
+
+---
+
+## Pull Request Review
+
+This project uses the pr-review plugin for automated code review.
+
+### Commands
+
+| Command | Use Case |
+|---------|----------|
+| `/pr-review <pr#>` | Full multi-agent review |
+| `/pr-summary <pr#>` | Quick change summary |
+| `/pr-findings <pr#>` | Filter review findings |
+
+### Review Categories
+
+Reviews analyze:
+- **Security**: Injections, auth issues, data exposure
+- **Performance**: N+1 queries, complexity, memory
+- **Maintainability**: Code quality, duplication, naming
+- **Tests**: Coverage gaps, test quality
+
+### Confidence Threshold
+
+Findings below 0.5 confidence are suppressed.
+
+- HIGH (0.9+): Definite issue
+- MEDIUM (0.7-0.89): Likely issue
+- LOW (0.5-0.69): Possible concern
+
+### Verdict Rules
+
+| Condition | Verdict |
+|-----------|---------|
+| Critical findings | REQUEST_CHANGES |
+| 2+ Major findings | REQUEST_CHANGES |
+| Minor only | COMMENT |
+| No issues | APPROVE |
+
+---
+
+Copy the section between the horizontal rules into your CLAUDE.md.

plugins/pr-review/commands/initial-setup.md

@@ -0,0 +1,273 @@
+---
+description: Interactive setup wizard for pr-review plugin - configures Gitea MCP and project settings
+---
+
+# PR Review Setup Wizard
+
+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.
+
+## Important Context
+
+- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
+- **MCP tools won't work until after setup + session restart**
+- **Shares Gitea MCP server with projman plugin**
+
+---
+
+## Phase 1: Check Existing Setup
+
+### Step 1.1: Check if Gitea MCP is Already Configured
+
+First, check if the system configuration already exists (from projman or previous setup):
+
+```bash
+cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
+```
+
+**If file exists with valid values (no placeholders):**
+- Skip to Phase 3 (Project Configuration)
+- Inform user: "Gitea configuration found. Skipping system setup."
+
+**If file doesn't exist or has placeholders:**
+- Continue to Phase 2
+
+### Step 1.2: Check if projman is Installed
+
+Check if projman plugin exists (they share MCP server):
+
+```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
+
+| Command | Description |
+|---------|-------------|
+| `/pr-review <number>` | Full multi-agent PR review with confidence scoring |
+| `/pr-summary <number>` | Quick PR summary |
+| `/pr-findings <number>` | List findings with severity and line numbers |

plugins/pr-review/commands/pr-findings.md

@@ -0,0 +1,137 @@
+# /pr-findings - Filter Review Findings
+
+## Purpose
+
+List and filter findings from a previous PR review by category, severity, or confidence level.
+
+## Usage
+
+```
+/pr-findings <pr-number> [filters]
+```
+
+### Filters
+
+```
+--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
+
+If no review exists for this PR:
+
+```
+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
+
+Display filtered findings:
+
+```
+═══════════════════════════════════════════════════
+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
+
+### Default (Detailed)
+
+Full finding details with descriptions and fixes.
+
+### Compact (--compact)
+
+```
+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

plugins/pr-review/commands/pr-review.md

@@ -0,0 +1,139 @@
+# /pr-review - Full Multi-Agent Review
+
+## Purpose
+
+Conduct a comprehensive pull request review using specialized agents for security, performance, maintainability, and test coverage.
+
+## Usage
+
+```
+/pr-review <pr-number> [--repo owner/repo]
+```
+
+## Behavior
+
+### Step 1: Fetch PR Data
+
+Using Gitea MCP tools:
+1. `get_pull_request` - PR metadata
+2. `get_pr_diff` - Code changes
+3. `get_pr_comments` - Existing discussion
+
+### Step 2: Dispatch to Agents
+
+The coordinator dispatches review tasks to specialized agents:
+
+```
+PR Review: #123 - Add user authentication
+═══════════════════════════════════════════════════
+
+Dispatching to review agents:
+├─ Security Reviewer     → analyzing...
+├─ Performance Analyst   → analyzing...
+├─ Maintainability Auditor → analyzing...
+└─ Test Validator        → analyzing...
+```
+
+### Step 3: Aggregate Findings
+
+Collect findings from all agents, each with:
+- 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
+
+Only display findings with confidence >= 0.5:
+
+| Confidence | Label | Description |
+|------------|-------|-------------|
+| 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 |
+| < 0.5 | (suppressed) | Too uncertain to report |
+
+### 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)
+
+```
+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
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Minimum confidence to report |
+| `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit to Gitea |

plugins/pr-review/commands/pr-summary.md

@@ -0,0 +1,103 @@
+# /pr-summary - Quick PR Summary
+
+## Purpose
+
+Generate a quick summary of PR changes without conducting a full multi-agent review.
+
+## Usage
+
+```
+/pr-summary <pr-number> [--repo owner/repo]
+```
+
+## Behavior
+
+### Step 1: Fetch PR Data
+
+Using Gitea MCP tools:
+1. `get_pull_request` - PR metadata
+2. `get_pr_diff` - Code changes
+
+### Step 2: Analyze Changes
+
+Quick analysis of:
+- Files modified
+- Types of changes (features, fixes, refactoring)
+- Scope and impact
+
+### Step 3: Generate Summary
+
+```
+═══════════════════════════════════════════════════
+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
+
+- Get quick overview before full review
+- Triage multiple PRs
+- Understand PR scope

plugins/pr-review/commands/project-init.md

@@ -0,0 +1,136 @@
+---
+description: Quick project setup - configures only project-level settings for PR review
+---
+
+# Project Initialization (PR Review)
+
+Fast setup for a new project when system-level configuration is already complete.
+
+**Use this when:**
+- 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
+
+---
+
+## Pre-Flight Check
+
+### Step 1: Verify System Configuration
+
+```bash
+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:**
+
+---
+
+**System configuration not found.**
+
+Please run `/initial-setup` first to configure Gitea credentials.
+
+---
+
+**If SYSTEM_OK:** Continue.
+
+---
+
+## 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
+```

plugins/pr-review/commands/project-sync.md

@@ -0,0 +1,93 @@
+---
+description: Sync project configuration with current git remote - use after changing repository location
+---
+
+# Project Sync (PR Review)
+
+Updates project configuration when the git remote URL has changed.
+
+**Use this when:**
+- Repository was moved to a different organization
+- Repository was renamed
+- Git remote URL changed
+- SessionStart hook detected a mismatch
+
+---
+
+## Step 1: Verify System Configuration
+
+```bash
+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.
+
+---
+
+## Step 2: Read Current .env
+
+```bash
+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>                                    ║
+╚══════════════════════════════════════════════════════════════╝
+```

plugins/pr-review/hooks/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "prompt",
+        "prompt": "[pr-review] Perform silent startup checks:\n\n1. Check if MCP venvs exist at the installed marketplace location. If the marketplace is installed but venvs are missing, warn the user: '[pr-review] MCP venvs missing - run setup.sh from installed marketplace location'.\n\n2. Check if the project git remote matches .env configuration (GITEA_ORG/GITEA_REPO). If mismatch, warn: '[pr-review] Git remote mismatch - run /project-sync'.\n\nStay silent if all checks pass or not applicable. Be quick and non-blocking."
+      }
+    ]
+  }
+}

plugins/pr-review/mcp-servers/gitea

@@ -0,0 +1 @@
+../../../mcp-servers/gitea

plugins/pr-review/skills/review-patterns/confidence-scoring.md

@@ -0,0 +1,139 @@
+# Confidence Scoring for PR Review
+
+## Purpose
+
+Confidence scoring ensures that review findings are calibrated and actionable. By filtering out low-confidence findings, we reduce noise and focus reviewer attention on real issues.
+
+## Score Ranges
+
+| Range | Label | Meaning | Action |
+|-------|-------|---------|--------|
+| 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 |
+| < 0.5 | SUPPRESSED | Uncertain | Don't report |
+
+## Scoring Factors
+
+### Positive Factors (Increase Confidence)
+
+| Factor | Impact |
+|--------|--------|
+| Clear data flow from source to sink | +0.3 |
+| Pattern matches known vulnerability | +0.2 |
+| No intervening validation visible | +0.2 |
+| Matches OWASP Top 10 | +0.15 |
+| Found in security-sensitive context | +0.1 |
+
+### Negative Factors (Decrease Confidence)
+
+| Factor | Impact |
+|--------|--------|
+| Validation might exist elsewhere | -0.2 |
+| Depends on runtime configuration | -0.15 |
+| Pattern is common but often safe | -0.15 |
+| Requires multiple conditions to exploit | -0.1 |
+| Theoretical impact only | -0.1 |
+
+## Calibration Guidelines
+
+### Security Issues
+
+Base confidence by pattern:
+- SQL string concatenation with user input: 0.95
+- Hardcoded credentials: 0.9
+- Missing auth check: 0.8
+- Generic error exposure: 0.6
+- Missing rate limiting: 0.5
+
+### Performance Issues
+
+Base confidence by pattern:
+- Clear N+1 in loop: 0.9
+- SELECT * on large table: 0.7
+- Missing index on filtered column: 0.6
+- Suboptimal algorithm: 0.5
+
+### Maintainability Issues
+
+Base confidence by pattern:
+- Function >100 lines: 0.8
+- Deep nesting >4 levels: 0.75
+- Duplicate code blocks: 0.7
+- Unclear naming: 0.6
+- Minor style issues: 0.3 (suppress)
+
+### Test Coverage
+
+Base confidence by pattern:
+- No test file for new module: 0.9
+- Security function untested: 0.85
+- Edge case not covered: 0.6
+- Simple getter untested: 0.3 (suppress)
+
+## Threshold Configuration
+
+The default threshold is 0.5. This can be adjusted:
+
+```bash
+PR_REVIEW_CONFIDENCE_THRESHOLD=0.7  # Only high-confidence
+PR_REVIEW_CONFIDENCE_THRESHOLD=0.3  # Include more speculative
+```
+
+## Example Scoring
+
+### High Confidence (0.95)
+
+```javascript
+// Clear SQL injection
+const query = `SELECT * FROM users WHERE id = ${req.params.id}`;
+```
+
+- User input (req.params.id): +0.3
+- Direct to SQL query: +0.3
+- No visible validation: +0.2
+- Matches OWASP Top 10: +0.15
+- **Total: 0.95**
+
+### Medium Confidence (0.72)
+
+```javascript
+// Possible performance issue
+users.forEach(async (user) => {
+  const orders = await db.orders.find({ userId: user.id });
+});
+```
+
+- Loop with query: +0.3
+- Pattern matches N+1: +0.2
+- But might be small dataset: -0.15
+- Could have caching: -0.1
+- **Total: 0.72**
+
+### Low Confidence (0.55)
+
+```javascript
+// Maybe too complex?
+function processOrder(order, user, items, discounts, shipping) {
+  // 60 lines of logic
+}
+```
+
+- Function is long: +0.2
+- Many parameters: +0.15
+- But might be intentional: -0.1
+- Could be refactored later: -0.1
+- **Total: 0.55**
+
+### Suppressed (0.35)
+
+```javascript
+// Minor style preference
+const x = foo ? bar : baz;
+```
+
+- Ternary could be if/else: +0.1
+- Very common pattern: -0.2
+- No real impact: -0.1
+- Style preference: -0.1
+- **Total: 0.35** (suppressed)

plugins/project-hygiene/.claude-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/project-hygiene/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": [
     "cleanup",

plugins/projman/.claude-plugin/plugin.json

@@ -1,13 +1,13 @@
 {
   "name": "projman",
-  "version": "2.3.0",
+  "version": "3.1.0",
   "description": "Sprint planning and project management with Gitea integration",
   "author": {
     "name": "Leo Miranda",
     "email": "leobmiranda@gmail.com"
   },
-  "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md",
+  "homepage": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace/src/branch/main/plugins/projman/README.md",
-  "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git",
+  "repository": "https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace.git",
   "license": "MIT",
   "keywords": [
     "project-management",
@@ -17,5 +17,5 @@
     "lessons-learned"
   ],
   "commands": ["./commands/"],
-  "agents": ["./agents/"]
+  "mcpServers": ["./.mcp.json"]
 }

plugins/projman/CONFIGURATION.md

@@ -1,441 +1,10 @@
-# Configuration Guide - Projman Plugin
+# Configuration - Projman Plugin
 
-Complete setup and configuration instructions for the Projman project management plugin.
+See **[docs/CONFIGURATION.md](../../docs/CONFIGURATION.md)** for complete setup instructions.
 
-## Overview
+## Quick Commands
 
-The Projman plugin uses a **hybrid configuration** approach:
-- **System-level:** Credentials for Gitea (stored once per machine)
-- **Project-level:** Repository path (stored per project)
-
-This design allows:
-- Single token per service (update once, use everywhere)
-- Easy multi-project setup (just add `.env` per project)
-- Security (tokens never committed to git)
-- Project isolation (each project has its own scope)
-
-## Prerequisites
-
-Before configuring the plugin, ensure you have:
-
-1. **Python 3.10+** installed
-   ```bash
-   python3 --version  # Should be 3.10.0 or higher
-   ```
-
-2. **Git repository** initialized
-   ```bash
-   git status  # Should show initialized repository
-   ```
-
-3. **Gitea access** with an account and permissions to:
-   - Create issues
-   - Manage labels
-   - Read organization information
-   - Access repository wiki
-
-4. **Claude Code** installed and working
-
-## Step 1: Install MCP Server
-
-The plugin bundles the Gitea MCP server at `mcp-servers/gitea/`:
-
-```bash
-# Navigate to MCP server directory (inside plugin)
-cd plugins/projman/mcp-servers/gitea
-
-# Create virtual environment
-python3 -m venv .venv
-
-# Activate virtual environment
-source .venv/bin/activate  # Linux/Mac
-# or
-.venv\Scripts\activate     # Windows
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Verify installation
-python -c "from mcp_server import server; print('Gitea MCP Server installed successfully')"
-
-# Deactivate when done
-deactivate
 ```
-
+/initial-setup    # First time on this machine
-## Step 2: Generate Gitea API Token
+/project-init     # New project (system already configured)
-
-1. Log into Gitea: https://gitea.example.com
-2. Navigate to: **User Icon** (top right) → **Settings**
-3. Click **Applications** tab
-4. Scroll to **Manage Access Tokens**
-5. Click **Generate New Token**
-6. Configure token:
-   - **Token Name:** `claude-code-projman`
-   - **Permissions:**
-     - `repo` (all sub-permissions) - Repository access
-     - `read:org` - Read organization information and labels
-     - `read:user` - Read user information
-     - `write:repo` - Wiki access
-7. Click **Generate Token**
-8. **IMPORTANT:** Copy token immediately (shown only once!)
-9. Save token securely - you'll need it in Step 3
-
-**Token Permissions Explained:**
-- `repo` - Create, read, update issues, labels, and wiki
-- `read:org` - Access organization-level labels
-- `read:user` - Associate issues with user account
-- `write:repo` - Create wiki pages for lessons learned
-
-## Step 3: System-Level Configuration
-
-Create system-wide configuration file in `~/.config/claude/`:
-
-### 3.1 Create Configuration Directory
-
-```bash
-mkdir -p ~/.config/claude
 ```
-
-### 3.2 Configure Gitea
-
-```bash
-cat > ~/.config/claude/gitea.env << 'EOF'
-# Gitea API Configuration
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=your_gitea_token_here
-GITEA_ORG=your_organization
-EOF
-
-# Secure the file (owner read/write only)
-chmod 600 ~/.config/claude/gitea.env
-```
-
-**Replace placeholders:**
-- `your_gitea_token_here` with the token from Step 2
-- `your_organization` with your Gitea organization name
-
-**Configuration Variables:**
-- `GITEA_URL` - Gitea base URL (without `/api/v1`)
-- `GITEA_TOKEN` - Personal access token from Step 2
-- `GITEA_ORG` - Organization name (e.g., `bandit`)
-
-### 3.3 Verify System Configuration
-
-```bash
-# Check file exists and has correct permissions
-ls -la ~/.config/claude/gitea.env
-
-# Should show:
-# -rw------- gitea.env
-```
-
-**Security Note:** File should have `600` permissions (owner read/write only) to protect API tokens.
-
-## Step 4: Project-Level Configuration
-
-For each project where you'll use Projman, create a `.env` file:
-
-### 4.1 Create Project .env File
-
-```bash
-# In your project root directory
-cat > .env << 'EOF'
-# Gitea Repository Configuration
-GITEA_REPO=your-repo-name
-EOF
-```
-
-**Example for MyProject:**
-```bash
-cat > .env << 'EOF'
-GITEA_REPO=my-project
-EOF
-```
-
-### 4.2 Verify Project Configuration
-
-```bash
-# Check .env exists
-ls -la .env
-
-# Check .env content
-cat .env
-```
-
-**Note:** The `.env` file may already be in your `.gitignore`. If your project uses `.env` for other purposes, the Gitea configuration will merge with existing variables.
-
-## Step 5: Configuration Verification
-
-Test that everything is configured correctly:
-
-### 5.1 Test Gitea Connection
-
-```bash
-# Test with curl
-curl -H "Authorization: token YOUR_GITEA_TOKEN" \
-  https://gitea.example.com/api/v1/user
-
-# Should return your user information in JSON format
-```
-
-### 5.2 Test Wiki Access
-
-```bash
-# Test wiki API
-curl -H "Authorization: token YOUR_GITEA_TOKEN" \
-  https://gitea.example.com/api/v1/repos/YOUR_ORG/YOUR_REPO/wiki/pages
-
-# Should return list of wiki pages (or empty array)
-```
-
-### 5.3 Test MCP Server Loading
-
-```bash
-# Navigate to plugin directory
-cd plugins/projman
-
-# Verify .mcp.json exists
-cat .mcp.json
-
-# Test loading (Claude Code will attempt to start MCP servers)
-claude --debug
-```
-
-## Step 6: Initialize Plugin
-
-### 6.1 Run Initial Setup
-
-```bash
-/initial-setup
-```
-
-This will:
-- Validate Gitea MCP server connection
-- Test credential configuration
-- Sync label taxonomy
-- Verify required directory structure
-
-### 6.2 Sync Label Taxonomy
-
-```bash
-/labels-sync
-```
-
-This will:
-- Fetch all labels from Gitea (organization + repository)
-- Update `skills/label-taxonomy/labels-reference.md`
-- Enable intelligent label suggestions
-
-### 6.3 Verify Commands Available
-
-```bash
-# List available commands
-/sprint-plan
-/sprint-start
-/sprint-status
-/sprint-close
-/labels-sync
-/initial-setup
-```
-
-## Configuration Files Reference
-
-### System-Level Files
-
-**`~/.config/claude/gitea.env`:**
-```bash
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx
-GITEA_ORG=your_organization
-```
-
-### Project-Level Files
-
-**`.env` (in project root):**
-```bash
-GITEA_REPO=your-repo-name
-```
-
-### Plugin Configuration
-
-**`projman/.mcp.json`:**
-```json
-{
-  "mcpServers": {
-    "gitea": {
-      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python",
-      "args": ["-m", "mcp_server.server"],
-      "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea",
-      "env": {
-        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea"
-      }
-    }
-  }
-}
-```
-
-## Multi-Project Setup
-
-To use Projman with multiple projects:
-
-1. **System config:** Set up once (already done in Step 3)
-2. **Project config:** Create `.env` in each project root:
-
-**Project 1: Main App**
-```bash
-# ~/projects/my-app/.env
-GITEA_REPO=my-app
-```
-
-**Project 2: App Site**
-```bash
-# ~/projects/my-app-site/.env
-GITEA_REPO=my-app-site
-```
-
-**Project 3: Company Site**
-```bash
-# ~/projects/company-site/.env
-GITEA_REPO=company-site
-```
-
-Each project operates independently with its own issues and lessons learned (stored in each repository's wiki).
-
-## Troubleshooting
-
-### Cannot find configuration files
-
-**Problem:** MCP server reports "Configuration not found"
-
-**Solution:**
-```bash
-# Check system config exists
-ls -la ~/.config/claude/gitea.env
-
-# If missing, recreate from Step 3
-```
-
-### Authentication failed
-
-**Problem:** "401 Unauthorized" or "Invalid token"
-
-**Solution:**
-```bash
-# Test Gitea token
-curl -H "Authorization: token YOUR_TOKEN" \
-  https://gitea.example.com/api/v1/user
-
-# If fails, regenerate token (Step 2)
-```
-
-### MCP server not starting
-
-**Problem:** "Failed to start MCP server"
-
-**Solution:**
-```bash
-# Check Python virtual environment exists
-ls plugins/projman/mcp-servers/gitea/.venv
-
-# If missing, reinstall (Step 1)
-
-# Check dependencies installed
-cd plugins/projman/mcp-servers/gitea
-source .venv/bin/activate
-python -c "import requests; import mcp"
-
-# If import fails, reinstall requirements
-pip install -r requirements.txt
-```
-
-### Wrong repository
-
-**Problem:** Issues created in wrong repo
-
-**Solution:**
-```bash
-# Check project .env configuration
-cat .env
-
-# Verify GITEA_REPO matches Gitea repository name exactly
-
-# Update if incorrect
-```
-
-### Permissions errors
-
-**Problem:** "Permission denied" when creating issues or wiki pages
-
-**Solution:**
-- Verify token has `repo`, `read:org`, and `write:repo` permissions (Step 2)
-- Regenerate token with correct permissions if needed
-
-### Repository not in organization
-
-**Problem:** "Repository must belong to configured organization"
-
-**Solution:**
-- Verify `GITEA_ORG` in system config matches the organization owning the repository
-- Verify `GITEA_REPO` belongs to that organization
-- Fork the repository to your organization if needed
-
-## Security Best Practices
-
-1. **Never commit tokens**
-   - Keep credentials in `~/.config/claude/` only
-   - Never hardcode tokens in code
-   - Use system-level config for credentials
-
-2. **Secure configuration files**
-   - Set `600` permissions on `~/.config/claude/*.env`
-   - Store in user home directory only
-   - Don't share token files
-
-3. **Rotate tokens periodically**
-   - Regenerate tokens every 6-12 months
-   - Immediately revoke if compromised
-   - Use separate tokens for dev/prod if needed
-
-4. **Minimum permissions**
-   - Only grant required permissions
-   - Gitea: `repo`, `read:org`, `read:user`, `write:repo`
-
-5. **Monitor usage**
-   - Review Gitea access logs periodically
-   - Watch for unexpected API usage
-
-## Next Steps
-
-After configuration is complete:
-
-1. Run `/initial-setup` to verify everything works
-2. Run `/labels-sync` to fetch label taxonomy
-3. Try `/sprint-plan` to start your first sprint
-4. Read [README.md](./README.md) for usage guide
-
-## Support
-
-**Configuration Issues:**
-- Check [README.md](./README.md) troubleshooting section
-- Contact repository maintainer for support
-
-**Questions:**
-- Read command documentation: `commands/*.md`
-- Check agent descriptions in `agents/`
-
----
-
-**Configuration Status Checklist:**
-
-- [ ] Python 3.10+ installed
-- [ ] Gitea MCP server installed (in `mcp-servers/gitea/`)
-- [ ] Gitea API token generated with correct permissions
-- [ ] System config created (`~/.config/claude/gitea.env`)
-- [ ] Project config created (`.env`)
-- [ ] Gitea connection tested
-- [ ] Wiki access tested
-- [ ] `/initial-setup` completed successfully
-- [ ] `/labels-sync` completed successfully
-- [ ] Commands verified available
-
-Once all items are checked, you're ready to use Projman!

plugins/projman/README.md

@@ -25,57 +25,38 @@ Projman transforms a proven 15-sprint workflow into a distributable Claude Code
 - Python 3.10+ installed
 - Git repository initialized
 
-### 2. Install MCP Server
+### 2. Run Interactive Setup
 
-The plugin bundles the Gitea MCP server:
+The setup wizard handles everything:
 
-```bash
-cd plugins/projman/mcp-servers/gitea
-python3 -m venv .venv
-source .venv/bin/activate  # or .venv\Scripts\activate on Windows
-pip install -r requirements.txt
 ```
-
-See [CONFIGURATION.md](./CONFIGURATION.md) for detailed setup instructions.
-
-### 3. Configure System-Level Settings
-
-Create system-wide configuration with your Gitea credentials:
-
-```bash
-mkdir -p ~/.config/claude
-
-# Gitea configuration
-cat > ~/.config/claude/gitea.env << 'EOF'
-GITEA_URL=https://gitea.example.com
-GITEA_TOKEN=your_gitea_token_here
-GITEA_ORG=your_organization
-EOF
-
-# Secure the file
-chmod 600 ~/.config/claude/gitea.env
-```
-
-### 4. Configure Project-Level Settings
-
-In your project root directory, create a `.env` file:
-
-```bash
-# In your project directory
-cat > .env << 'EOF'
-GITEA_REPO=your-repo-name
-EOF
-```
-
-### 5. Run Initial Setup
-
-```bash
 /initial-setup
 ```
 
-### 6. Start Planning!
+This will:
+- Set up the MCP server (Python venv + dependencies)
+- Create system config (`~/.config/claude/gitea.env`)
+- Guide you through adding your Gitea token
+- Detect and validate your repository via API
+- Create project config (`.env`)
 
-```bash
+**For new projects** (when system is already configured):
+
+```
+/project-init
+```
+
+**After moving a repository:**
+
+```
+/project-sync
+```
+
+See [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md) for detailed instructions.
+
+### 3. Start Planning!
+
+```
 /sprint-plan
 ```
 
@@ -164,15 +145,42 @@ Synchronize label taxonomy from Gitea.
 - When new labels are added to Gitea
 
 ### `/initial-setup`
-Run initial setup for a new project.
+Full interactive setup wizard.
 
 **What it does:**
-- Validates Gitea MCP server connection
+- Checks Python version (requires 3.10+)
-- Tests credential configuration
+- Sets up MCP server virtual environment
-- Syncs label taxonomy
+- Creates system-level config (`~/.config/claude/gitea.env`)
-- Creates required directory structure
+- Guides token setup (manual entry for security)
+- Detects and validates repository via Gitea API
+- Creates project-level config (`.env` with GITEA_ORG, GITEA_REPO)
 
-**When to use:** First time setting up projman for a project
+**When to use:** First time on a new machine
+
+### `/project-init`
+Quick project setup (assumes system config exists).
+
+**What it does:**
+- Verifies system configuration exists
+- Detects organization and repository from git remote
+- Validates via Gitea API
+- Creates project `.env` file
+
+**When to use:** Starting work on a new project
+
+### `/project-sync`
+Sync configuration with current git remote.
+
+**What it does:**
+- Compares .env values with git remote URL
+- Validates new repository via Gitea API
+- Updates .env if mismatch detected
+
+**When to use:** After moving or renaming a repository
+
+**Note:** A SessionStart hook automatically checks for:
+1. Missing MCP venvs at the installed marketplace location (warns to run setup.sh)
+2. Repository config mismatches (warns to run `/project-sync`)
 
 ### `/review`
 Pre-sprint-close code quality review.
@@ -226,6 +234,39 @@ Generate tests for specified code.
 
 **When to use:** When adding new code that needs test coverage
 
+## Debug Workflow Commands
+
+These commands enable a cross-repository debugging workflow between your project and the marketplace.
+
+### `/debug-report`
+Run diagnostics and create structured issue in marketplace repository.
+
+**What it does:**
+- Runs MCP tool diagnostics (validate_repo_org, get_labels, list_issues, etc.)
+- Captures error messages and hypothesis
+- Creates a structured issue in the marketplace repository
+- Tags with `Source: Diagnostic` label
+
+**When to use:** When MCP tools fail in your project, run this to report the issue to the marketplace for investigation.
+
+### `/debug-review`
+Investigate diagnostic issues and propose fixes with human approval.
+
+**What it does:**
+- Fetches open diagnostic issues from marketplace
+- Lets you select which issue to investigate
+- Maps errors to relevant source files
+- Reads code and analyzes root cause
+- Proposes fixes with THREE mandatory approval gates
+- Creates PR with fix after approval
+
+**Approval Gates:**
+1. Analysis confirmation - Does the investigation match your understanding?
+2. Fix approach - Proceed with proposed changes?
+3. PR creation - Create pull request?
+
+**When to use:** In the marketplace repo, to investigate and fix issues reported by `/debug-report`.
+
 ## Code Quality Commands
 
 The `/review` and `/test-check` commands complement the Executor agent by catching issues before work is marked complete. Run both commands before `/sprint-close` for a complete quality check.
@@ -441,9 +482,13 @@ projman/
 │   ├── sprint-close.md
 │   ├── labels-sync.md
 │   ├── initial-setup.md
+│   ├── project-init.md
+│   ├── project-sync.md
 │   ├── review.md
 │   ├── test-check.md
-│   └── test-gen.md
+│   ├── test-gen.md
+│   ├── debug-report.md
+│   └── debug-review.md
 ├── agents/                  # Agent prompts
 │   ├── planner.md
 │   ├── orchestrator.md

plugins/projman/commands/debug-report.md

@@ -0,0 +1,342 @@
+---
+description: Run diagnostics and create structured issue in marketplace repository
+---
+
+# Debug Report
+
+Run diagnostic checks on projman MCP tools and create a structured issue in the marketplace repository for investigation.
+
+## Prerequisites
+
+Your project `.env` must have:
+
+```env
+PROJMAN_MARKETPLACE_REPO=personal-projects/leo-claude-mktplace
+```
+
+If not configured, ask the user for the marketplace repository path.
+
+## CRITICAL: Execution Steps
+
+You MUST follow these steps in order. Do NOT skip any step.
+
+### Step 1: Gather Project Context
+
+Run these Bash commands to capture project information:
+
+```bash
+# Get git remote URL
+git remote get-url origin
+
+# Get current branch
+git branch --show-current
+
+# Get working directory
+pwd
+```
+
+Parse the git remote to extract `REPO_NAME` in `owner/repo` format.
+
+Store all values:
+- `PROJECT_REPO`: The detected owner/repo
+- `GIT_REMOTE`: Full git remote URL
+- `CURRENT_BRANCH`: Current branch name
+- `WORKING_DIR`: Current working directory
+
+### Step 2: Read Marketplace Configuration
+
+```bash
+grep PROJMAN_MARKETPLACE_REPO .env
+```
+
+Store as `MARKETPLACE_REPO`. If not found, ask the user.
+
+### Step 3: Run Diagnostic Suite
+
+Run each MCP tool with explicit `repo` parameter. Record success/failure and full response.
+
+**Test 1: validate_repo_org**
+```
+mcp__plugin_projman_gitea__validate_repo_org(repo=PROJECT_REPO)
+```
+Expected: `{is_organization: true/false}`
+
+**Test 2: get_labels**
+```
+mcp__plugin_projman_gitea__get_labels(repo=PROJECT_REPO)
+```
+Expected: `{organization: [...], repository: [...], total_count: N}`
+
+**Test 3: list_issues**
+```
+mcp__plugin_projman_gitea__list_issues(repo=PROJECT_REPO, state="open")
+```
+Expected: Array of issues
+
+**Test 4: list_milestones**
+```
+mcp__plugin_projman_gitea__list_milestones(repo=PROJECT_REPO)
+```
+Expected: Array of milestones
+
+**Test 5: suggest_labels**
+```
+mcp__plugin_projman_gitea__suggest_labels(context="Test bug fix for authentication")
+```
+Expected: Array of label names matching repo's format
+
+For each test, record:
+- Tool name
+- Exact parameters used
+- Status: PASS or FAIL
+- Response or error message
+
+### Step 4: Analyze Results
+
+Count failures and categorize errors:
+
+| Category | Indicators |
+|----------|------------|
+| Parameter Format | "owner/repo format", "missing parameter" |
+| Authentication | "401", "403", "unauthorized" |
+| Not Found | "404", "not found" |
+| Network | "connection", "timeout", "ECONNREFUSED" |
+| Logic | Unexpected response format, wrong data |
+
+For each failure, write a hypothesis about the likely cause.
+
+### Step 5: Generate Issue Content
+
+Use this exact template:
+
+```markdown
+## Diagnostic Report
+
+**Generated**: [ISO timestamp]
+**Command Tested**: [What the user was trying to run, or "general diagnostic"]
+**Reporter**: Claude Code via /debug-report
+
+## Project Context
+
+| Field | Value |
+|-------|-------|
+| Repository | `[PROJECT_REPO]` |
+| Git Remote | `[GIT_REMOTE]` |
+| Working Directory | `[WORKING_DIR]` |
+| Current Branch | `[CURRENT_BRANCH]` |
+
+## Diagnostic Results
+
+### Test 1: validate_repo_org
+
+**Call**: `validate_repo_org(repo="[PROJECT_REPO]")`
+**Status**: [PASS/FAIL]
+**Response**:
+```json
+[full response or error]
+```
+
+### Test 2: get_labels
+
+**Call**: `get_labels(repo="[PROJECT_REPO]")`
+**Status**: [PASS/FAIL]
+**Response**:
+```json
+[full response or error - truncate if very long]
+```
+
+[... repeat for each test ...]
+
+## Summary
+
+- **Total Tests**: 5
+- **Passed**: [N]
+- **Failed**: [N]
+
+### Failed Tools
+
+[List each failed tool with its error]
+
+### Error Category
+
+[Check applicable categories]
+
+### Hypothesis
+
+[Your analysis of what's wrong and why]
+
+### Suggested Investigation
+
+1. [First file/function to check]
+2. [Second file/function to check]
+3. [etc.]
+
+## Reproduction Steps
+
+1. Navigate to `[WORKING_DIR]`
+2. Run `[command that was being tested]`
+3. Observe error at step [X]
+
+---
+
+*Generated by /debug-report - Labels: Type: Bug, Source: Diagnostic, Agent: Claude*
+```
+
+### Step 6: Create Issue in Marketplace
+
+**First, check if MCP tools are available.** Attempt to use an MCP tool. If you receive "tool not found", "not in function list", or similar error, the MCP server is not accessible in this session - use the curl fallback.
+
+#### Option A: MCP Available (preferred)
+
+```
+mcp__plugin_projman_gitea__create_issue(
+  repo=MARKETPLACE_REPO,
+  title="[Diagnostic] [summary of main failure]",
+  body=[generated content from Step 5],
+  labels=["Type: Bug", "Source: Diagnostic", "Agent: Claude"]
+)
+```
+
+If labels don't exist, create issue without labels.
+
+#### Option B: MCP Unavailable - Use curl Fallback
+
+If MCP tools are not available (the very issue you may be diagnosing), use this fallback:
+
+**1. Check for Gitea credentials:**
+
+```bash
+if [[ -f ~/.config/claude/gitea.env ]]; then
+  source ~/.config/claude/gitea.env
+  echo "Credentials found. API URL: $GITEA_API_URL"
+else
+  echo "No credentials at ~/.config/claude/gitea.env"
+fi
+```
+
+**2. If credentials exist, create issue via curl with proper JSON escaping:**
+
+Create secure temp files and save content:
+
+```bash
+# Create temp files with restrictive permissions
+DIAG_TITLE=$(mktemp -p /tmp -m 600 diag-title.XXXXXX)
+DIAG_BODY=$(mktemp -p /tmp -m 600 diag-body.XXXXXX)
+DIAG_PAYLOAD=$(mktemp -p /tmp -m 600 diag-payload.XXXXXX)
+
+# Save title
+echo "[Diagnostic] [summary of main failure]" > "$DIAG_TITLE"
+
+# Save body (paste Step 5 content) - heredoc delimiter prevents shell expansion
+cat > "$DIAG_BODY" << 'DIAGNOSTIC_EOF'
+[Paste the full issue content from Step 5 here]
+DIAGNOSTIC_EOF
+```
+
+Construct JSON safely using jq's --rawfile (avoids command substitution):
+
+```bash
+# Build JSON payload using jq with --rawfile for safe content handling
+jq -n \
+  --rawfile title "$DIAG_TITLE" \
+  --rawfile body "$DIAG_BODY" \
+  '{title: ($title | rtrimstr("\n")), body: $body}' > "$DIAG_PAYLOAD"
+
+# Create issue using the JSON file
+curl -s -X POST "${GITEA_API_URL}/repos/${MARKETPLACE_REPO}/issues" \
+  -H "Authorization: token ${GITEA_API_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d @"$DIAG_PAYLOAD" | jq '.html_url // .'
+
+# Secure cleanup
+rm -f "$DIAG_TITLE" "$DIAG_BODY" "$DIAG_PAYLOAD"
+```
+
+**3. If no credentials found, save report locally:**
+
+```bash
+REPORT_FILE=$(mktemp -p /tmp -m 600 diagnostic-report-XXXXXX.md)
+cat > "$REPORT_FILE" << 'DIAGNOSTIC_EOF'
+[Paste the full issue content from Step 5 here]
+DIAGNOSTIC_EOF
+echo "Report saved to: $REPORT_FILE"
+```
+
+Then inform the user:
+
+```
+MCP tools are unavailable and no Gitea credentials found at ~/.config/claude/gitea.env.
+
+Diagnostic report saved to: [REPORT_FILE]
+
+To create the issue manually:
+1. Configure credentials: See docs/CONFIGURATION.md
+2. Or create issue directly at: http://gitea.hotserv.cloud/[MARKETPLACE_REPO]/issues/new
+```
+
+### Step 7: Report to User
+
+Display summary:
+
+```
+Debug Report Complete
+=====================
+
+Project: [PROJECT_REPO]
+Tests Run: 5
+Passed: [N]
+Failed: [N]
+
+Failed Tools:
+  - [tool1]: [brief error]
+  - [tool2]: [brief error]
+
+Issue Created: [issue URL]
+
+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 tests pass (just report success)
+- **DO NOT** skip any diagnostic test
+- **DO NOT** call MCP tools without the `repo` parameter
+- **DO NOT** ask user questions during execution - run autonomously
+
+## If All Tests Pass
+
+If all 5 tests pass, report success without creating an issue:
+
+```
+Debug Report Complete
+=====================
+
+Project: [PROJECT_REPO]
+Tests Run: 5
+Passed: 5
+Failed: 0
+
+All diagnostics passed. No issues to report.
+
+If you're experiencing a specific problem, please describe it
+and I can create a manual bug report.
+```
+
+## Troubleshooting
+
+**PROJMAN_MARKETPLACE_REPO not configured**
+- Ask user: "What is the marketplace repository? (e.g., personal-projects/leo-claude-mktplace)"
+- Store for this session and remind user to add to .env
+
+**Cannot detect project repository**
+- Check if in a git repository: `git rev-parse --git-dir`
+- If not a git repo, ask user for the repository path
+
+**MCP tools not available**
+- Use the curl fallback in Step 6, Option B
+- Requires Gitea credentials at `~/.config/claude/gitea.env`
+- If no credentials, report will be saved locally for manual submission

plugins/projman/commands/debug-review.md

@@ -0,0 +1,394 @@
+---
+description: Investigate diagnostic issues and propose fixes with human approval
+---
+
+# Debug Review
+
+Investigate diagnostic issues created by `/debug-report`, read relevant code, and propose fixes with human approval at each step.
+
+## CRITICAL: This Command Requires Human Approval
+
+This command has THREE mandatory approval gates. You MUST stop and wait for user confirmation at each gate before proceeding.
+
+## Execution Steps
+
+### Step 1: Detect Repository
+
+Run Bash to get the current repository:
+
+```bash
+git remote get-url origin
+```
+
+Parse to extract `REPO_NAME` in `owner/repo` format.
+
+### Step 2: Fetch Diagnostic Issues
+
+```
+mcp__plugin_projman_gitea__list_issues(
+  repo=REPO_NAME,
+  state="open",
+  labels=["Source: Diagnostic"]
+)
+```
+
+If no issues with that label, try without label filter and look for issues with "[Diagnostic]" in title.
+
+### Step 3: Display Issue List
+
+Show the user available issues:
+
+```
+Debug Review
+============
+
+Open Diagnostic Issues:
+
+  #80 - [Diagnostic] get_labels fails without repo parameter
+        Created: 2026-01-21 | Labels: Type: Bug, Source: Diagnostic
+
+  #77 - [Diagnostic] MCP tools require explicit repo parameter
+        Created: 2026-01-21 | Labels: Type: Bug, Source: Diagnostic
+
+No diagnostic issues? Showing recent bugs:
+
+  #75 - [Bug] Some other issue
+        Created: 2026-01-20
+```
+
+### Step 4: User Selects Issue
+
+Use AskUserQuestion:
+
+```
+Which issue would you like to investigate?
+Options: [List issue numbers]
+```
+
+Wait for user selection.
+
+### Step 5: Fetch Full Issue Details
+
+```
+mcp__plugin_projman_gitea__get_issue(repo=REPO_NAME, issue_number=SELECTED)
+```
+
+### Step 6: Parse Diagnostic Report
+
+Extract from the issue body:
+
+1. **Failed Tools**: Which MCP tools failed
+2. **Error Messages**: Exact error text
+3. **Hypothesis**: Reporter's analysis
+4. **Suggested Investigation**: Files to check
+5. **Project Context**: Repo, branch, cwd where error occurred
+
+If the issue doesn't follow the diagnostic template, extract what information is available.
+
+### Step 7: Map Errors to Code Files
+
+Use this mapping to identify relevant files:
+
+**By Tool Name:**
+| Tool | Primary Files |
+|------|---------------|
+| `validate_repo_org` | `mcp-servers/gitea/mcp_server/gitea_client.py` |
+| `get_labels` | `mcp-servers/gitea/mcp_server/tools/labels.py` |
+| `suggest_labels` | `mcp-servers/gitea/mcp_server/tools/labels.py` |
+| `list_issues` | `mcp-servers/gitea/mcp_server/tools/issues.py` |
+| `create_issue` | `mcp-servers/gitea/mcp_server/tools/issues.py` |
+| `list_milestones` | `mcp-servers/gitea/mcp_server/gitea_client.py` |
+
+**By Error Pattern:**
+| Error Contains | Check Files |
+|----------------|-------------|
+| "owner/repo format" | `config.py`, `gitea_client.py` |
+| "404" + "orgs" | `gitea_client.py` (is_org_repo method) |
+| "401", "403" | `config.py` (token loading) |
+| "No repository" | Command `.md` file (repo detection step) |
+
+**By Command:**
+| Command | Documentation File |
+|---------|-------------------|
+| `/labels-sync` | `plugins/projman/commands/labels-sync.md` |
+| `/sprint-plan` | `plugins/projman/commands/sprint-plan.md` |
+| `/sprint-start` | `plugins/projman/commands/sprint-start.md` |
+| `/debug-report` | `plugins/projman/commands/debug-report.md` |
+
+### Step 8: Read Relevant Files (MANDATORY)
+
+You MUST read the identified files before proposing any fix.
+
+For each relevant file:
+1. Read the file using the Read tool
+2. Find the specific function/method mentioned in the error
+3. Understand the code path that leads to the error
+4. Note any related code that might be affected
+
+Display snippets of relevant code to the user:
+
+```
+Reading relevant files...
+
+┌─ mcp-servers/gitea/mcp_server/tools/labels.py (lines 29-40) ────────┐
+│                                                                      │
+│ async def get_labels(self, repo: Optional[str] = None):              │
+│     target_repo = repo or self.gitea.repo                            │
+│     if not target_repo or '/' not in target_repo:                    │
+│         raise ValueError("Use 'owner/repo' format...")               │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 9: Present Investigation Summary
+
+Summarize what you found:
+
+```
+Investigation Summary
+=====================
+
+ISSUE: #80 - get_labels fails without repo parameter
+
+FAILED TOOLS:
+  • get_labels - "Use 'owner/repo' format"
+
+CODE ANALYSIS:
+
+1. labels.py:get_labels() requires repo parameter
+   - Line 30: `target_repo = repo or self.gitea.repo`
+   - Line 31-32: Raises ValueError if no repo
+
+2. labels-sync.md documents Step 1 for repo detection
+   - Lines 13-26: Instructs to run `git remote get-url origin`
+   - This step may not be followed by executing Claude
+
+ROOT CAUSE HYPOTHESIS:
+
+The command documentation (labels-sync.md) correctly instructs
+repo detection, but the executing Claude may be skipping Step 1
+and calling MCP tools directly.
+
+Evidence:
+  • Error indicates repo parameter was not passed
+  • labels-sync.md has correct instructions
+  • MCP server cannot auto-detect (sandboxed environment)
+
+LIKELY FIX:
+
+Option A: Make Step 1 more prominent in labels-sync.md
+Option B: Add validation that repo was detected before proceeding
+Option C: [Other based on analysis]
+```
+
+## APPROVAL GATE 1
+
+```
+Does this analysis match your understanding of the problem?
+
+[Y] Yes, proceed to propose fix
+[N] No, let me clarify
+[R] Read more files first
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT proceed until user approves.
+
+### Step 10: Propose Fix Approach
+
+Based on the analysis, propose a specific fix:
+
+```
+Proposed Fix
+============
+
+APPROACH: [A/B/C from above]
+
+CHANGES NEEDED:
+
+1. File: plugins/projman/commands/labels-sync.md
+   Change: Add warning box after Step 1 emphasizing repo must be detected
+
+2. File: [if applicable]
+   Change: [description]
+
+RATIONALE:
+
+[Explain why this fix addresses the root cause]
+
+RISKS:
+
+[Any potential issues with this approach]
+```
+
+## APPROVAL GATE 2
+
+```
+Proceed with this fix approach?
+
+[Y] Yes, implement it
+[N] No, try different approach
+[M] Modify the approach (tell me what to change)
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT implement until user approves.
+
+### Step 11: Implement Fix
+
+Only after user approves:
+
+1. Create feature branch:
+```bash
+git checkout -b fix/issue-[NUMBER]-[brief-description]
+```
+
+2. Make the code changes using Edit tool
+
+3. Run relevant tests if they exist:
+```bash
+cd mcp-servers/gitea && .venv/bin/python -m pytest tests/ -v
+```
+
+4. Show the changes to user:
+```bash
+git diff
+```
+
+### Step 12: Present Changes
+
+```
+Changes Implemented
+===================
+
+Branch: fix/issue-80-labels-sync-instructions
+
+Files Modified:
+  • plugins/projman/commands/labels-sync.md (+15, -3)
+
+Diff Summary:
+[Show git diff output]
+
+Test Results:
+  • 23 passed, 0 failed (or N/A if no tests)
+```
+
+## APPROVAL GATE 3
+
+```
+Create PR with these changes?
+
+[Y] Yes, create PR
+[N] No, I want to modify something
+[D] Discard changes
+```
+
+**STOP HERE AND WAIT FOR USER RESPONSE**
+
+Do NOT create PR until user approves.
+
+### Step 13: Create PR
+
+Only after user approves:
+
+1. Commit changes:
+```bash
+git add -A
+git commit -m "fix: [description]
+
+[Longer explanation]
+
+Fixes #[ISSUE_NUMBER]
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+```
+
+2. Push branch:
+```bash
+git push -u origin fix/issue-[NUMBER]-[brief-description]
+```
+
+3. Create PR via API or MCP tools
+
+4. **Switch back to development branch** (required for MCP issue operations):
+```bash
+git checkout development
+```
+
+5. Add comment to original issue:
+```
+mcp__plugin_projman_gitea__add_comment(
+  repo=REPO_NAME,
+  issue_number=ISSUE_NUMBER,
+  comment="Fix proposed in PR #[PR_NUMBER]\n\nChanges:\n- [summary]\n\nPlease test after merge and report back."
+)
+```
+
+### Step 14: Report Completion
+
+```
+Debug Review Complete
+=====================
+
+Issue: #80 - get_labels fails without repo parameter
+Status: Fix Proposed
+
+PR Created: #81 - fix: improve labels-sync repo detection instructions
+URL: http://gitea.hotserv.cloud/.../pulls/81
+
+Next Steps:
+  1. Review and merge PR #81
+  2. In test project, pull latest plugin version
+  3. Run /debug-report to verify fix
+  4. If passing, close issue #80
+```
+
+## DO NOT
+
+- **DO NOT** skip reading relevant files - this is MANDATORY
+- **DO NOT** proceed past approval gates without user confirmation
+- **DO NOT** guess at fixes without evidence from code
+- **DO NOT** close issues - let user verify fix works first
+- **DO NOT** commit directly to development or main branches
+
+## If Investigation Finds No Bug
+
+Sometimes investigation reveals the issue is:
+- User error (didn't follow documented steps)
+- Configuration issue (missing .env vars)
+- Already fixed in a newer version
+
+In this case:
+
+```
+Investigation Summary
+=====================
+
+FINDING: This does not appear to be a code bug.
+
+ANALYSIS:
+[Explanation of what you found]
+
+RECOMMENDATION:
+[ ] Close issue as "not a bug" - user error
+[ ] Close issue as "duplicate" of #[X]
+[ ] Add documentation to prevent confusion
+[ ] Other: [specify]
+
+Would you like me to add a comment explaining this finding?
+```
+
+## Error-to-File Quick Reference
+
+```
+Error Message                    → File to Check
+─────────────────────────────────────────────────────────────────
+"Use 'owner/repo' format"        → config.py, gitea_client.py
+"404 Client Error.*orgs"         → gitea_client.py (_is_organization)
+"No repository specified"        → Command .md file (Step 1)
+"401 Unauthorized"               → config.py (token loading)
+"labels not found"               → labels.py, gitea_client.py
+"create local.*file"             → Command .md file (DO NOT section)
+```