From e5ca804692a92b026acfc967c179c2a1132a8464 Mon Sep 17 00:00:00 2001 From: lmiranda Date: Tue, 20 Jan 2026 16:56:53 -0500 Subject: [PATCH 1/2] feat: v3.0.0 architecture overhaul - Rename marketplace to lm-claude-plugins - Move MCP servers to root with symlinks - Add 6 PR tools to Gitea MCP (list_pull_requests, get_pull_request, get_pr_diff, get_pr_comments, create_pr_review, add_pr_comment) - Add clarity-assist plugin (prompt optimization with ND accommodations) - Add git-flow plugin (workflow automation) - Add pr-review plugin (multi-agent review with confidence scoring) - Centralize configuration docs - Update all documentation for v3.0.0 BREAKING CHANGE: MCP server paths changed, marketplace renamed Co-Authored-By: Claude Opus 4.5 --- .claude-plugin/marketplace.json | 87 +++- CHANGELOG.md | 55 ++- CLAUDE.md | 65 +-- README.md | 211 ++++----- docs/CANONICAL-PATHS.md | 149 ++++-- docs/CONFIGURATION.md | 380 +++++++++++++++ .../gitea/README.md | 0 .../gitea/TESTING.md | 0 .../gitea/mcp_server/__init__.py | 0 .../gitea/mcp_server/config.py | 0 .../gitea/mcp_server/gitea_client.py | 123 +++++ .../gitea/mcp_server/server.py | 163 +++++++ .../gitea/mcp_server/tools/__init__.py | 4 + .../gitea/mcp_server/tools/dependencies.py | 0 .../gitea/mcp_server/tools/issues.py | 0 .../gitea/mcp_server/tools/labels.py | 0 .../gitea/mcp_server/tools/milestones.py | 0 .../gitea/mcp_server/tools/pull_requests.py | 274 +++++++++++ .../gitea/mcp_server/tools/wiki.py | 0 .../gitea/requirements.txt | 0 .../gitea/tests/__init__.py | 0 .../gitea/tests/test_config.py | 0 .../gitea/tests/test_gitea_client.py | 0 .../gitea/tests/test_issues.py | 0 .../gitea/tests/test_labels.py | 0 .../netbox/README.md | 0 .../netbox/mcp_server/__init__.py | 0 .../netbox/mcp_server/config.py | 0 .../netbox/mcp_server/netbox_client.py | 0 .../netbox/mcp_server/server.py | 0 .../netbox/mcp_server/tools/__init__.py | 0 .../netbox/mcp_server/tools/circuits.py | 0 .../netbox/mcp_server/tools/dcim.py | 0 .../netbox/mcp_server/tools/extras.py | 0 .../netbox/mcp_server/tools/ipam.py | 0 .../netbox/mcp_server/tools/tenancy.py | 0 .../netbox/mcp_server/tools/virtualization.py | 0 .../netbox/mcp_server/tools/vpn.py | 0 .../netbox/mcp_server/tools/wireless.py | 0 .../netbox/requirements.txt | 0 .../netbox/tests/__init__.py | 0 .../clarity-assist/.claude-plugin/plugin.json | 45 ++ plugins/clarity-assist/README.md | 99 ++++ .../clarity-assist/agents/clarity-coach.md | 140 ++++++ .../clarity-assist/claude-md-integration.md | 58 +++ plugins/clarity-assist/commands/clarify.md | 137 ++++++ .../clarity-assist/commands/quick-clarify.md | 84 ++++ .../prompt-patterns/optimization-rules.md | 134 ++++++ plugins/cmdb-assistant/mcp-servers/netbox | 1 + plugins/git-flow/.claude-plugin/plugin.json | 75 +++ plugins/git-flow/README.md | 128 +++++ plugins/git-flow/agents/git-assistant.md | 139 ++++++ plugins/git-flow/claude-md-integration.md | 55 +++ plugins/git-flow/commands/branch-cleanup.md | 94 ++++ plugins/git-flow/commands/branch-start.md | 96 ++++ plugins/git-flow/commands/commit-merge.md | 83 ++++ plugins/git-flow/commands/commit-push.md | 57 +++ plugins/git-flow/commands/commit-sync.md | 79 ++++ plugins/git-flow/commands/commit.md | 117 +++++ plugins/git-flow/commands/git-config.md | 100 ++++ plugins/git-flow/commands/git-status.md | 72 +++ .../workflow-patterns/branching-strategies.md | 183 ++++++++ plugins/pr-review/.claude-plugin/plugin.json | 71 +++ plugins/pr-review/.mcp.json | 9 + plugins/pr-review/README.md | 126 +++++ plugins/pr-review/agents/coordinator.md | 133 ++++++ .../agents/maintainability-auditor.md | 99 ++++ .../pr-review/agents/performance-analyst.md | 93 ++++ plugins/pr-review/agents/security-reviewer.md | 93 ++++ plugins/pr-review/agents/test-validator.md | 110 +++++ plugins/pr-review/claude-md-integration.md | 46 ++ plugins/pr-review/commands/pr-findings.md | 137 ++++++ plugins/pr-review/commands/pr-review.md | 139 ++++++ plugins/pr-review/commands/pr-summary.md | 103 ++++ plugins/pr-review/mcp-servers/gitea | 1 + .../review-patterns/confidence-scoring.md | 139 ++++++ plugins/projman/CONFIGURATION.md | 440 +----------------- plugins/projman/mcp-servers/gitea | 1 + scripts/post-update.sh | 3 +- scripts/setup.sh | 162 +++---- scripts/validate-marketplace.sh | 60 +++ 81 files changed, 4747 insertions(+), 705 deletions(-) create mode 100644 docs/CONFIGURATION.md rename {plugins/projman/mcp-servers => mcp-servers}/gitea/README.md (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/TESTING.md (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/__init__.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/config.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/gitea_client.py (82%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/server.py (81%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/__init__.py (50%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/dependencies.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/issues.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/labels.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/milestones.py (100%) create mode 100644 mcp-servers/gitea/mcp_server/tools/pull_requests.py rename {plugins/projman/mcp-servers => mcp-servers}/gitea/mcp_server/tools/wiki.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/requirements.txt (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/tests/__init__.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/tests/test_config.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/tests/test_gitea_client.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/tests/test_issues.py (100%) rename {plugins/projman/mcp-servers => mcp-servers}/gitea/tests/test_labels.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/README.md (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/__init__.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/config.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/netbox_client.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/server.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/__init__.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/circuits.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/dcim.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/extras.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/ipam.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/tenancy.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/virtualization.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/vpn.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/mcp_server/tools/wireless.py (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/requirements.txt (100%) rename {plugins/cmdb-assistant/mcp-servers => mcp-servers}/netbox/tests/__init__.py (100%) create mode 100644 plugins/clarity-assist/.claude-plugin/plugin.json create mode 100644 plugins/clarity-assist/README.md create mode 100644 plugins/clarity-assist/agents/clarity-coach.md create mode 100644 plugins/clarity-assist/claude-md-integration.md create mode 100644 plugins/clarity-assist/commands/clarify.md create mode 100644 plugins/clarity-assist/commands/quick-clarify.md create mode 100644 plugins/clarity-assist/skills/prompt-patterns/optimization-rules.md create mode 120000 plugins/cmdb-assistant/mcp-servers/netbox create mode 100644 plugins/git-flow/.claude-plugin/plugin.json create mode 100644 plugins/git-flow/README.md create mode 100644 plugins/git-flow/agents/git-assistant.md create mode 100644 plugins/git-flow/claude-md-integration.md create mode 100644 plugins/git-flow/commands/branch-cleanup.md create mode 100644 plugins/git-flow/commands/branch-start.md create mode 100644 plugins/git-flow/commands/commit-merge.md create mode 100644 plugins/git-flow/commands/commit-push.md create mode 100644 plugins/git-flow/commands/commit-sync.md create mode 100644 plugins/git-flow/commands/commit.md create mode 100644 plugins/git-flow/commands/git-config.md create mode 100644 plugins/git-flow/commands/git-status.md create mode 100644 plugins/git-flow/skills/workflow-patterns/branching-strategies.md create mode 100644 plugins/pr-review/.claude-plugin/plugin.json create mode 100644 plugins/pr-review/.mcp.json create mode 100644 plugins/pr-review/README.md create mode 100644 plugins/pr-review/agents/coordinator.md create mode 100644 plugins/pr-review/agents/maintainability-auditor.md create mode 100644 plugins/pr-review/agents/performance-analyst.md create mode 100644 plugins/pr-review/agents/security-reviewer.md create mode 100644 plugins/pr-review/agents/test-validator.md create mode 100644 plugins/pr-review/claude-md-integration.md create mode 100644 plugins/pr-review/commands/pr-findings.md create mode 100644 plugins/pr-review/commands/pr-review.md create mode 100644 plugins/pr-review/commands/pr-summary.md create mode 120000 plugins/pr-review/mcp-servers/gitea create mode 100644 plugins/pr-review/skills/review-patterns/confidence-scoring.md create mode 120000 plugins/projman/mcp-servers/gitea diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e61d06d..73a6d28 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,17 +1,17 @@ { - "name": "claude-code-marketplace", + "name": "lm-claude-plugins", "owner": { "name": "Leo Miranda", "email": "leobmiranda@gmail.com" }, "metadata": { "description": "Project management plugins with Gitea and NetBox integrations", - "version": "2.3.0" + "version": "3.0.0" }, "plugins": [ { "name": "projman", - "version": "2.3.0", + "version": "3.0.0", "description": "Sprint planning and project management with Gitea integration", "source": "./plugins/projman", "author": { @@ -21,7 +21,10 @@ "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/projman/README.md", "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": ["gitea"], - "integrationFile": "claude-md-integration.md" + "integrationFile": "claude-md-integration.md", + "category": "development", + "tags": ["sprint", "agile", "gitea", "project-management"], + "license": "MIT" }, { "name": "doc-guardian", @@ -36,7 +39,10 @@ "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": [], "integrationFile": "claude-md-integration.md", - "hooks": ["PostToolUse", "Stop"] + "hooks": ["PostToolUse", "Stop"], + "category": "productivity", + "tags": ["documentation", "drift-detection", "sync"], + "license": "MIT" }, { "name": "code-sentinel", @@ -51,7 +57,10 @@ "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": [], "integrationFile": "claude-md-integration.md", - "hooks": ["PreToolUse"] + "hooks": ["PreToolUse"], + "category": "security", + "tags": ["security-scan", "refactoring", "vulnerabilities"], + "license": "MIT" }, { "name": "project-hygiene", @@ -66,7 +75,10 @@ "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": [], "integrationFile": "claude-md-integration.md", - "hooks": ["PostToolUse"] + "hooks": ["PostToolUse"], + "category": "productivity", + "tags": ["cleanup", "automation", "hygiene"], + "license": "MIT" }, { "name": "cmdb-assistant", @@ -80,7 +92,10 @@ "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/cmdb-assistant/README.md", "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": ["netbox"], - "integrationFile": "claude-md-integration.md" + "integrationFile": "claude-md-integration.md", + "category": "infrastructure", + "tags": ["cmdb", "netbox", "dcim", "ipam"], + "license": "MIT" }, { "name": "claude-config-maintainer", @@ -94,7 +109,61 @@ "homepage": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace/src/branch/main/plugins/claude-config-maintainer/README.md", "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", "mcpServers": [], - "integrationFile": "claude-md-integration.md" + "integrationFile": "claude-md-integration.md", + "category": "development", + "tags": ["claude-md", "configuration", "optimization"], + "license": "MIT" + }, + { + "name": "clarity-assist", + "version": "1.0.0", + "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/support-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "mcpServers": [], + "integrationFile": "claude-md-integration.md", + "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/support-claude-mktplace/src/branch/main/plugins/git-flow/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "mcpServers": [], + "integrationFile": "claude-md-integration.md", + "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/support-claude-mktplace/src/branch/main/plugins/pr-review/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "mcpServers": ["gitea"], + "integrationFile": "claude-md-integration.md", + "category": "development", + "tags": ["code-review", "pull-requests", "security", "quality"], + "license": "MIT" } ], "pluginDetection": { diff --git a/CHANGELOG.md b/CHANGELOG.md index 7600b71..92eccac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,62 @@ # Changelog -All notable changes to support-claude-mktplace will be documented in this file. +All notable changes to lm-claude-plugins will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## [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 `lm-claude-plugins` +- **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 diff --git a/CLAUDE.md b/CLAUDE.md index 09b8b55..a87381c 100644 --- a/CLAUDE.md +++ b/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 -**Version:** 2.3.0 +**Repository:** lm-claude-plugins +**Version:** 3.0.0 **Status:** Production Ready A Claude Code plugin marketplace 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 | @@ -36,34 +39,36 @@ A Claude Code plugin marketplace containing: ## Repository Structure ``` -support-claude-mktplace/ +lm-claude-plugins/ ├── .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 -│ │ │ ├── sprint-plan.md, sprint-start.md, sprint-status.md -│ │ │ ├── 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 (NEW v3.0.0) +│ │ ├── .claude-plugin/plugin.json +│ │ ├── commands/ # 8 commands +│ │ └── agents/ +│ ├── pr-review/ # Multi-agent PR review (NEW v3.0.0) +│ │ ├── .claude-plugin/plugin.json +│ │ ├── .mcp.json +│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK +│ │ ├── commands/ # 3 commands +│ │ └── 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 +77,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 +91,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 +104,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,6 +126,7 @@ 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 @@ -160,10 +167,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` -5. Update `CHANGELOG.md` +4. If using MCP server, create symlink: `ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}` +5. Run `./scripts/validate-marketplace.sh` +6. Update `CHANGELOG.md` ### Adding a Command to projman @@ -191,8 +199,9 @@ Stored in Gitea Wiki under `lessons-learned/sprints/`. | Document | Purpose | |----------|---------| | `docs/CANONICAL-PATHS.md` | **Single source of truth** for paths | +| `docs/CONFIGURATION.md` | Centralized setup guide | | `docs/UPDATING.md` | Update guide for the marketplace | -| `plugins/projman/CONFIGURATION.md` | Projman setup guide | +| `plugins/projman/CONFIGURATION.md` | Quick reference (links to central) | | `plugins/projman/README.md` | Projman full documentation | ## Versioning and Changelog Rules diff --git a/README.md b/README.md index 906f82e..25441f4 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,17 @@ -# Claude Code Marketplace - v2.3.0 +# Claude Code Marketplace - v3.0.0 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 @@ -19,67 +21,86 @@ AI-guided sprint planning with full Gitea integration. Transforms a proven 15-sp **Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/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` + +#### [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) -**NetBox CMDB Integration** +### Productivity -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 -- Smart search across all NetBox modules -- Conversational infrastructure queries -- Audit trail and change tracking +Transform vague requests into clear specifications using structured methodology. -**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.) -- Warns about unexpected files in project root -- Identifies orphaned supporting files -- Configurable via `.hygiene.json` +### Security -### [doc-guardian](./plugins/doc-guardian/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) +#### [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:** `/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. @@ -125,7 +147,7 @@ Add to `.claude/settings.json` in your target project: ```json { "extraKnownMarketplaces": { - "support-claude-mktplace": { + "lm-claude-plugins": { "source": { "source": "git", "url": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git" @@ -135,34 +157,20 @@ Add to `.claude/settings.json` in your target project: } ``` -**Option 3 - Local development:** -```bash -# Clone the repository first -git clone https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git - -# Then add from local path -/plugin marketplace add /path/to/support-claude-mktplace -``` - -**Alternative SSH URL (for authenticated access):** -``` -ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git -``` - ### Configure MCP Server Dependencies -If using plugins with MCP servers (projman, cmdb-assistant), install dependencies: +Install dependencies for shared MCP servers: ```bash -# Gitea MCP (for projman) -cd plugins/projman/mcp-servers/gitea +# Gitea MCP (for projman, pr-review) +cd 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 +cd ../netbox python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt @@ -171,7 +179,9 @@ deactivate ### Configure Credentials -**System-level credentials:** +See [docs/CONFIGURATION.md](./docs/CONFIGURATION.md) for complete setup instructions. + +**Quick start:** ```bash mkdir -p ~/.config/claude @@ -181,19 +191,9 @@ GITEA_URL=https://gitea.example.com GITEA_TOKEN=your_token GITEA_ORG=your_org EOF +chmod 600 ~/.config/claude/gitea.env -# NetBox credentials -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 -``` - -**Project-level settings:** -```bash -# In your target project root +# Project-level settings cat > .env << 'EOF' GITEA_REPO=your-repository-name EOF @@ -202,64 +202,36 @@ EOF ## Repository Structure ``` -support-claude-mktplace/ +lm-claude-plugins/ ├── .claude-plugin/ # Marketplace manifest │ └── marketplace.json -├── plugins/ # All plugins (with bundled MCP servers) -│ ├── projman/ # Sprint management plugin -│ │ ├── .claude-plugin/ -│ │ ├── .mcp.json -│ │ ├── mcp-servers/ # Bundled MCP server -│ │ │ └── gitea/ -│ │ ├── commands/ -│ │ ├── agents/ -│ │ └── skills/ -│ ├── claude-config-maintainer/ # CLAUDE.md optimization plugin -│ │ ├── .claude-plugin/ -│ │ ├── commands/ -│ │ └── agents/ +├── mcp-servers/ # SHARED MCP servers (v3.0.0+) +│ ├── gitea/ # Gitea MCP (issues, PRs, wiki) +│ └── netbox/ # NetBox MCP (CMDB) +├── plugins/ # All plugins +│ ├── projman/ # Sprint management +│ ├── git-flow/ # Git workflow automation (NEW) +│ ├── pr-review/ # PR review (NEW) +│ ├── clarity-assist/ # Prompt optimization (NEW) +│ ├── claude-config-maintainer/ # CLAUDE.md optimization │ ├── 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 -├── docs/ # Reference documentation -│ ├── CANONICAL-PATHS.md # Single source of truth for paths -│ └── references/ -└── scripts/ # Setup and maintenance scripts - └── validate-marketplace.sh # Marketplace compliance validation +│ ├── code-sentinel/ # Security scanning +│ └── project-hygiene/ # Cleanup automation +├── docs/ # Documentation +│ ├── CANONICAL-PATHS.md # Path reference +│ └── CONFIGURATION.md # Setup guide +└── 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] : ` -- **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 | | [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 @@ -269,4 +241,3 @@ MIT License - **Issues**: Contact repository maintainer - **Repository**: `https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git` -- **SSH URL**: `ssh://git@hotserv.tailc9b278.ts.net:2222/personal-projects/support-claude-mktplace.git` diff --git a/docs/CANONICAL-PATHS.md b/docs/CANONICAL-PATHS.md index 2465479..23e89c6 100644 --- a/docs/CANONICAL-PATHS.md +++ b/docs/CANONICAL-PATHS.md @@ -2,64 +2,106 @@ **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/ +lm-claude-plugins/ ├── .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 │ ├── UPDATING.md # Update guide │ └── workflows/ # Workflow documentation ├── hooks/ # Shared hooks (if any) -├── plugins/ # ALL plugins with bundled MCP servers -│ ├── projman/ +├── mcp-servers/ # SHARED MCP servers (v3.0.0+) +│ ├── 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 -│ │ │ └── gitea/ # Gitea + Wiki tools +│ │ ├── .mcp.json +│ │ ├── 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/ +│ ├── cmdb-assistant/ # NetBox CMDB integration │ │ ├── .claude-plugin/ -│ │ ├── mcp-servers/ # MCP servers bundled IN plugin -│ │ │ └── netbox/ +│ │ ├── .mcp.json +│ │ ├── 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 -│ └── project-hygiene/ +│ │ └── claude-md-integration.md +│ ├── 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/ -│ └── claude-md-integration.md # CLAUDE.md integration snippet +│ ├── .mcp.json +│ ├── mcp-servers/ +│ │ └── gitea -> ../../../mcp-servers/gitea # SYMLINK +│ ├── commands/ +│ ├── agents/ +│ ├── skills/ +│ └── claude-md-integration.md ├── scripts/ # Setup and maintenance scripts ├── CLAUDE.md ├── README.md @@ -83,22 +125,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/` | -| MCP server code | `plugins/{plugin}/mcp-servers/{server}/mcp_server/` | `plugins/projman/mcp-servers/gitea/mcp_server/` | -| MCP venv | `plugins/{plugin}/mcp-servers/{server}/.venv/` | `plugins/projman/mcp-servers/gitea/.venv/` | +| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` | +| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` | +| 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 | -|------|----|---------| -| Plugin .mcp.json | Bundled MCP server | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{server}` | -| marketplace.json | Plugin | `./plugins/{plugin-name}` | +Plugins that use MCP servers create symlinks: +```bash +# From plugin directory +ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea +``` + +The symlink target is relative: `../../../mcp-servers/{server}` ### Documentation Paths @@ -108,6 +154,7 @@ 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` | --- @@ -125,15 +172,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/ -With variable: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/ +Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python ``` From `.claude-plugin/marketplace.json` to `plugins/projman/`: @@ -152,18 +199,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/` | -| `../../mcp-servers/` from plugin | Old pattern, doesn't work with caching | `${CLAUDE_PLUGIN_ROOT}/mcp-servers/` | -| `./../../../plugins/projman` in marketplace | Wrong (old nested structure) | `./plugins/projman` | +| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` | +| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` | +| 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: -- Claude Code caches only the plugin directory when installed -- Relative paths to parent directories break in the cache -- Each plugin must be self-contained to work properly +MCP servers are now **shared at repository root** with **symlinks** from plugins: + +**Benefits:** +- 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 +228,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 lm-claude-plugins | 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 | -| 2025-12-15 | Restructured: MCP servers now bundled in plugins | Claude Code | +| 2026-01-19 | Added claude-md-integration.md path pattern | Claude Code | +| 2025-12-15 | Restructured: MCP servers bundled in plugins | Claude Code | | 2025-12-12 | Initial creation | Claude Code | diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md new file mode 100644 index 0000000..0a646e1 --- /dev/null +++ b/docs/CONFIGURATION.md @@ -0,0 +1,380 @@ +# Configuration Guide + +Centralized configuration documentation for all plugins and MCP servers in the lm-claude-plugins marketplace. + +## Overview + +This marketplace uses a **hybrid configuration** approach: +- **System-level:** Credentials and service configuration (stored once per machine) +- **Project-level:** Repository-specific settings (stored per project) + +**Benefits:** +- 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 any plugin: + +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. **Claude Code** installed and working + +--- + +## System-Level Configuration + +Configuration files stored in `~/.config/claude/`: + +```bash +mkdir -p ~/.config/claude +``` + +### Gitea Configuration + +Required by: `projman`, `pr-review` + +```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 +chmod 600 ~/.config/claude/gitea.env +``` + +**Variables:** +| Variable | Description | Example | +|----------|-------------|---------| +| `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` | +| `GITEA_TOKEN` | Personal access token | `glpat-xxx...` | +| `GITEA_ORG` | Organization name | `bandit` | + +**Generating 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) +4. Copy token immediately (shown only once) + +### NetBox Configuration + +Required by: `cmdb-assistant` + +```bash +cat > ~/.config/claude/netbox.env << 'EOF' +# NetBox API Configuration +NETBOX_URL=https://netbox.example.com +NETBOX_TOKEN=your_netbox_token_here +EOF + +chmod 600 ~/.config/claude/netbox.env +``` + +**Variables:** +| Variable | Description | Example | +|----------|-------------|---------| +| `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` | +| `NETBOX_TOKEN` | API token | `abc123...` | + +### Git-Flow Configuration + +Optional system defaults for: `git-flow` + +```bash +cat > ~/.config/claude/git-flow.env << 'EOF' +# Git-Flow Default Configuration +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 +EOF +``` + +--- + +## Project-Level Configuration + +Create `.env` in each project root: + +### Gitea Repository (projman, pr-review) + +```bash +# .env in project root +GITEA_REPO=your-repo-name +``` + +### Git-Flow (project overrides) + +```bash +# .env in project root +GIT_WORKFLOW_STYLE=pr-required +GIT_DEFAULT_BASE=main +``` + +### PR Review + +```bash +# .env in project root +PR_REVIEW_CONFIDENCE_THRESHOLD=0.5 +PR_REVIEW_AUTO_SUBMIT=false +``` + +--- + +## MCP Server Installation + +MCP servers are located at repository root: `mcp-servers/` + +### Gitea MCP Server + +```bash +cd mcp-servers/gitea + +# Create virtual environment +python3 -m venv .venv + +# Activate +source .venv/bin/activate + +# Install dependencies +pip install -r requirements.txt + +# Verify +python -c "from mcp_server import server; print('OK')" + +deactivate +``` + +### NetBox MCP Server + +```bash +cd mcp-servers/netbox + +# Create virtual environment +python3 -m venv .venv + +# Activate +source .venv/bin/activate + +# Install dependencies +pip install -r requirements.txt + +# Verify +python -c "from mcp_server import server; print('OK')" + +deactivate +``` + +--- + +## Plugin Configuration Reference + +### projman + +| Level | Variable | Default | Description | +|-------|----------|---------|-------------| +| System | `GITEA_URL` | (required) | Gitea API base URL | +| System | `GITEA_TOKEN` | (required) | API token | +| System | `GITEA_ORG` | (required) | Organization name | +| Project | `GITEA_REPO` | (required) | Repository name | + +**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen` + +### pr-review + +| Level | Variable | Default | Description | +|-------|----------|---------|-------------| +| System | `GITEA_URL` | (required) | Gitea API base URL | +| System | `GITEA_TOKEN` | (required) | API token | +| Project | `GITEA_REPO` | (required) | Repository name | +| Project | `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Minimum confidence | +| Project | `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews | + +**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings` + +### git-flow + +| Level | Variable | Default | Description | +|-------|----------|---------|-------------| +| System/Project | `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy | +| System/Project | `GIT_DEFAULT_BASE` | `development` | Default base branch | +| System/Project | `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches | +| System/Project | `GIT_AUTO_PUSH` | `false` | Auto-push after commit | +| System/Project | `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches | +| System/Project | `GIT_COMMIT_STYLE` | `conventional` | Commit message style | +| System/Project | `GIT_CO_AUTHOR` | `true` | Include Claude co-author | + +**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config` + +### clarity-assist + +No configuration required. Uses sensible defaults. + +**Commands:** `/clarify`, `/quick-clarify` + +### cmdb-assistant + +| Level | Variable | Default | Description | +|-------|----------|---------|-------------| +| System | `NETBOX_URL` | (required) | NetBox API base URL | +| System | `NETBOX_TOKEN` | (required) | API token | + +### doc-guardian + +No configuration required. Hook-based plugin. + +### code-sentinel + +No configuration required. Hook-based plugin. + +### project-hygiene + +No configuration required. Hook-based plugin. + +### claude-config-maintainer + +No configuration required. + +--- + +## Multi-Project Setup + +1. **System config:** Set up once (credentials) +2. **Project config:** Create `.env` in each project root + +**Example:** +```bash +# ~/projects/my-app/.env +GITEA_REPO=my-app + +# ~/projects/another-app/.env +GITEA_REPO=another-app +GIT_WORKFLOW_STYLE=trunk-based +``` + +--- + +## Verification + +### Test Gitea Connection + +```bash +curl -H "Authorization: token YOUR_TOKEN" \ + https://gitea.example.com/api/v1/user +``` + +### Test MCP Server + +```bash +cd mcp-servers/gitea +source .venv/bin/activate +python -c "from mcp_server import server; print('OK')" +``` + +### Run Plugin Setup + +```bash +# For projman +/initial-setup +/labels-sync +``` + +--- + +## Troubleshooting + +### Configuration not found + +```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 +curl -H "Authorization: token YOUR_TOKEN" \ + https://gitea.example.com/api/v1/user + +# Regenerate if invalid +``` + +### MCP server not starting + +```bash +# Check venv exists +ls mcp-servers/gitea/.venv + +# Reinstall if missing +cd mcp-servers/gitea +python3 -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +### Wrong repository + +```bash +# Check project .env +cat .env + +# Verify GITEA_REPO matches 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. **Rotate tokens periodically** + - Every 6-12 months + - Immediately if compromised + +4. **Minimum permissions** + - Only grant required token permissions + - Use separate tokens for different environments + +--- + +## Quick Setup Checklist + +- [ ] Python 3.10+ installed +- [ ] `~/.config/claude/` directory created +- [ ] Service credentials configured (gitea.env, netbox.env) +- [ ] Configuration files secured (chmod 600) +- [ ] MCP servers installed with venv +- [ ] Project `.env` created with repository settings +- [ ] Connections tested +- [ ] Plugin commands verified diff --git a/plugins/projman/mcp-servers/gitea/README.md b/mcp-servers/gitea/README.md similarity index 100% rename from plugins/projman/mcp-servers/gitea/README.md rename to mcp-servers/gitea/README.md diff --git a/plugins/projman/mcp-servers/gitea/TESTING.md b/mcp-servers/gitea/TESTING.md similarity index 100% rename from plugins/projman/mcp-servers/gitea/TESTING.md rename to mcp-servers/gitea/TESTING.md diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/__init__.py b/mcp-servers/gitea/mcp_server/__init__.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/__init__.py rename to mcp-servers/gitea/mcp_server/__init__.py diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/config.py b/mcp-servers/gitea/mcp_server/config.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/config.py rename to mcp-servers/gitea/mcp_server/config.py diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/gitea_client.py b/mcp-servers/gitea/mcp_server/gitea_client.py similarity index 82% rename from plugins/projman/mcp-servers/gitea/mcp_server/gitea_client.py rename to mcp-servers/gitea/mcp_server/gitea_client.py index 0fe82fe..00bf677 100644 --- a/plugins/projman/mcp-servers/gitea/mcp_server/gitea_client.py +++ b/mcp-servers/gitea/mcp_server/gitea_client.py @@ -591,3 +591,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() diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/server.py b/mcp-servers/gitea/mcp_server/server.py similarity index 81% rename from plugins/projman/mcp-servers/gitea/mcp_server/server.py rename to mcp-servers/gitea/mcp_server/server.py index 039de82..b99a6dc 100644 --- a/plugins/projman/mcp-servers/gitea/mcp_server/server.py +++ b/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: @@ -638,6 +641,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 +876,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}") diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/__init__.py b/mcp-servers/gitea/mcp_server/tools/__init__.py similarity index 50% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/__init__.py rename to mcp-servers/gitea/mcp_server/tools/__init__.py index ab270b2..59b89aa 100644 --- a/plugins/projman/mcp-servers/gitea/mcp_server/tools/__init__.py +++ b/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) """ diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/dependencies.py b/mcp-servers/gitea/mcp_server/tools/dependencies.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/dependencies.py rename to mcp-servers/gitea/mcp_server/tools/dependencies.py diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/issues.py b/mcp-servers/gitea/mcp_server/tools/issues.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/issues.py rename to mcp-servers/gitea/mcp_server/tools/issues.py diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/labels.py b/mcp-servers/gitea/mcp_server/tools/labels.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/labels.py rename to mcp-servers/gitea/mcp_server/tools/labels.py diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/milestones.py b/mcp-servers/gitea/mcp_server/tools/milestones.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/milestones.py rename to mcp-servers/gitea/mcp_server/tools/milestones.py diff --git a/mcp-servers/gitea/mcp_server/tools/pull_requests.py b/mcp-servers/gitea/mcp_server/tools/pull_requests.py new file mode 100644 index 0000000..b6bd831 --- /dev/null +++ b/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) + ) diff --git a/plugins/projman/mcp-servers/gitea/mcp_server/tools/wiki.py b/mcp-servers/gitea/mcp_server/tools/wiki.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/mcp_server/tools/wiki.py rename to mcp-servers/gitea/mcp_server/tools/wiki.py diff --git a/plugins/projman/mcp-servers/gitea/requirements.txt b/mcp-servers/gitea/requirements.txt similarity index 100% rename from plugins/projman/mcp-servers/gitea/requirements.txt rename to mcp-servers/gitea/requirements.txt diff --git a/plugins/projman/mcp-servers/gitea/tests/__init__.py b/mcp-servers/gitea/tests/__init__.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/tests/__init__.py rename to mcp-servers/gitea/tests/__init__.py diff --git a/plugins/projman/mcp-servers/gitea/tests/test_config.py b/mcp-servers/gitea/tests/test_config.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/tests/test_config.py rename to mcp-servers/gitea/tests/test_config.py diff --git a/plugins/projman/mcp-servers/gitea/tests/test_gitea_client.py b/mcp-servers/gitea/tests/test_gitea_client.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/tests/test_gitea_client.py rename to mcp-servers/gitea/tests/test_gitea_client.py diff --git a/plugins/projman/mcp-servers/gitea/tests/test_issues.py b/mcp-servers/gitea/tests/test_issues.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/tests/test_issues.py rename to mcp-servers/gitea/tests/test_issues.py diff --git a/plugins/projman/mcp-servers/gitea/tests/test_labels.py b/mcp-servers/gitea/tests/test_labels.py similarity index 100% rename from plugins/projman/mcp-servers/gitea/tests/test_labels.py rename to mcp-servers/gitea/tests/test_labels.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/README.md b/mcp-servers/netbox/README.md similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/README.md rename to mcp-servers/netbox/README.md diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/__init__.py b/mcp-servers/netbox/mcp_server/__init__.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/__init__.py rename to mcp-servers/netbox/mcp_server/__init__.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/config.py b/mcp-servers/netbox/mcp_server/config.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/config.py rename to mcp-servers/netbox/mcp_server/config.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/netbox_client.py b/mcp-servers/netbox/mcp_server/netbox_client.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/netbox_client.py rename to mcp-servers/netbox/mcp_server/netbox_client.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/server.py b/mcp-servers/netbox/mcp_server/server.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/server.py rename to mcp-servers/netbox/mcp_server/server.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/__init__.py b/mcp-servers/netbox/mcp_server/tools/__init__.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/__init__.py rename to mcp-servers/netbox/mcp_server/tools/__init__.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/circuits.py b/mcp-servers/netbox/mcp_server/tools/circuits.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/circuits.py rename to mcp-servers/netbox/mcp_server/tools/circuits.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/dcim.py b/mcp-servers/netbox/mcp_server/tools/dcim.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/dcim.py rename to mcp-servers/netbox/mcp_server/tools/dcim.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/extras.py b/mcp-servers/netbox/mcp_server/tools/extras.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/extras.py rename to mcp-servers/netbox/mcp_server/tools/extras.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/ipam.py b/mcp-servers/netbox/mcp_server/tools/ipam.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/ipam.py rename to mcp-servers/netbox/mcp_server/tools/ipam.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/tenancy.py b/mcp-servers/netbox/mcp_server/tools/tenancy.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/tenancy.py rename to mcp-servers/netbox/mcp_server/tools/tenancy.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/virtualization.py b/mcp-servers/netbox/mcp_server/tools/virtualization.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/virtualization.py rename to mcp-servers/netbox/mcp_server/tools/virtualization.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/vpn.py b/mcp-servers/netbox/mcp_server/tools/vpn.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/vpn.py rename to mcp-servers/netbox/mcp_server/tools/vpn.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/wireless.py b/mcp-servers/netbox/mcp_server/tools/wireless.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/mcp_server/tools/wireless.py rename to mcp-servers/netbox/mcp_server/tools/wireless.py diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/requirements.txt b/mcp-servers/netbox/requirements.txt similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/requirements.txt rename to mcp-servers/netbox/requirements.txt diff --git a/plugins/cmdb-assistant/mcp-servers/netbox/tests/__init__.py b/mcp-servers/netbox/tests/__init__.py similarity index 100% rename from plugins/cmdb-assistant/mcp-servers/netbox/tests/__init__.py rename to mcp-servers/netbox/tests/__init__.py diff --git a/plugins/clarity-assist/.claude-plugin/plugin.json b/plugins/clarity-assist/.claude-plugin/plugin.json new file mode 100644 index 0000000..ab70dfa --- /dev/null +++ b/plugins/clarity-assist/.claude-plugin/plugin.json @@ -0,0 +1,45 @@ +{ + "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/support-claude-mktplace/src/branch/main/plugins/clarity-assist/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": [ + "prompt-optimization", + "clarification", + "neurodivergent", + "requirements", + "methodology" + ], + "commands": [ + { + "name": "clarify", + "description": "Full 4-D prompt optimization (Deconstruct, Diagnose, Develop, Deliver)", + "file": "commands/clarify.md" + }, + { + "name": "quick-clarify", + "description": "Rapid mode - single-pass clarification for simple requests", + "file": "commands/quick-clarify.md" + } + ], + "agents": [ + { + "name": "clarity-coach", + "description": "ND-friendly coach for structured requirement gathering", + "file": "agents/clarity-coach.md" + } + ], + "skills": [ + { + "name": "prompt-patterns", + "description": "Optimization rules and patterns for effective prompts", + "path": "skills/prompt-patterns" + } + ] +} diff --git a/plugins/clarity-assist/README.md b/plugins/clarity-assist/README.md new file mode 100644 index 0000000..e47f4a7 --- /dev/null +++ b/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 diff --git a/plugins/clarity-assist/agents/clarity-coach.md b/plugins/clarity-assist/agents/clarity-coach.md new file mode 100644 index 0000000..f4c60f0 --- /dev/null +++ b/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. diff --git a/plugins/clarity-assist/claude-md-integration.md b/plugins/clarity-assist/claude-md-integration.md new file mode 100644 index 0000000..37f76b1 --- /dev/null +++ b/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. diff --git a/plugins/clarity-assist/commands/clarify.md b/plugins/clarity-assist/commands/clarify.md new file mode 100644 index 0000000..13088cb --- /dev/null +++ b/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. diff --git a/plugins/clarity-assist/commands/quick-clarify.md b/plugins/clarity-assist/commands/quick-clarify.md new file mode 100644 index 0000000..47890cf --- /dev/null +++ b/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. diff --git a/plugins/clarity-assist/skills/prompt-patterns/optimization-rules.md b/plugins/clarity-assist/skills/prompt-patterns/optimization-rules.md new file mode 100644 index 0000000..0d676ec --- /dev/null +++ b/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 diff --git a/plugins/cmdb-assistant/mcp-servers/netbox b/plugins/cmdb-assistant/mcp-servers/netbox new file mode 120000 index 0000000..7ccbf12 --- /dev/null +++ b/plugins/cmdb-assistant/mcp-servers/netbox @@ -0,0 +1 @@ +../../../mcp-servers/netbox \ No newline at end of file diff --git a/plugins/git-flow/.claude-plugin/plugin.json b/plugins/git-flow/.claude-plugin/plugin.json new file mode 100644 index 0000000..e5a616a --- /dev/null +++ b/plugins/git-flow/.claude-plugin/plugin.json @@ -0,0 +1,75 @@ +{ + "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/support-claude-mktplace/src/branch/main/plugins/git-flow/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": [ + "git", + "workflow", + "commit", + "branch", + "automation" + ], + "commands": [ + { + "name": "commit", + "description": "Create a commit with auto-generated conventional message", + "file": "commands/commit.md" + }, + { + "name": "commit-push", + "description": "Commit and push to remote in one operation", + "file": "commands/commit-push.md" + }, + { + "name": "commit-merge", + "description": "Commit current changes and merge into target branch", + "file": "commands/commit-merge.md" + }, + { + "name": "commit-sync", + "description": "Commit, push, and sync with upstream", + "file": "commands/commit-sync.md" + }, + { + "name": "branch-start", + "description": "Start a new feature/fix/chore branch with naming convention", + "file": "commands/branch-start.md" + }, + { + "name": "branch-cleanup", + "description": "Clean up merged branches locally and optionally remotely", + "file": "commands/branch-cleanup.md" + }, + { + "name": "git-status", + "description": "Enhanced git status with recommendations", + "file": "commands/git-status.md" + }, + { + "name": "git-config", + "description": "Configure git-flow settings for this project", + "file": "commands/git-config.md" + } + ], + "agents": [ + { + "name": "git-assistant", + "description": "Git workflow assistant for complex operations", + "file": "agents/git-assistant.md" + } + ], + "skills": [ + { + "name": "workflow-patterns", + "description": "Git branching strategies and workflow patterns", + "path": "skills/workflow-patterns" + } + ] +} diff --git a/plugins/git-flow/README.md b/plugins/git-flow/README.md new file mode 100644 index 0000000..a2f3fec --- /dev/null +++ b/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 diff --git a/plugins/git-flow/agents/git-assistant.md b/plugins/git-flow/agents/git-assistant.md new file mode 100644 index 0000000..6b7070c --- /dev/null +++ b/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 diff --git a/plugins/git-flow/claude-md-integration.md b/plugins/git-flow/claude-md-integration.md new file mode 100644 index 0000000..4236eee --- /dev/null +++ b/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: `/` + +Types: feat, fix, chore, docs, refactor, test, perf + +Examples: +- `feat/add-user-auth` +- `fix/login-timeout` +- `chore/update-deps` + +### Commit Messages + +Use conventional commits: + +``` +(): + +[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. diff --git a/plugins/git-flow/commands/branch-cleanup.md b/plugins/git-flow/commands/branch-cleanup.md new file mode 100644 index 0000000..128a48d --- /dev/null +++ b/plugins/git-flow/commands/branch-cleanup.md @@ -0,0 +1,94 @@ +# /branch-cleanup - Clean Merged Branches + +## Purpose + +Remove branches that have been merged, both locally and optionally on remote. + +## Behavior + +### Step 1: Identify Merged Branches + +```bash +# Find merged local branches +git branch --merged + +# Find merged remote branches +git branch -r --merged +``` + +### Step 2: Present Findings + +``` +Found 5 merged branches: + +Local: + - feat/login-page (merged 3 days ago) + - fix/typo-header (merged 1 week ago) + - chore/deps-update (merged 2 weeks ago) + +Remote: + - origin/feat/login-page + - origin/fix/typo-header + +Protected (won't delete): + - main + - development + - staging + +Delete these branches? +1. Delete all (local + remote) +2. Delete local only +3. Let me pick which ones +4. Cancel +``` + +### Step 3: Execute Cleanup + +```bash +# Delete local +git branch -d + +# Delete remote +git push origin --delete +``` + +### Step 4: Report + +``` +Cleanup complete: + +Deleted local: 3 branches +Deleted remote: 2 branches +Skipped: 0 branches + +Remaining local branches: + - main + - development + - feat/current-work (not merged) +``` + +## 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 | + +## Safety + +- Never deletes protected branches +- Warns about unmerged branches +- Confirms before deleting remote branches +- Uses `-d` (safe delete) not `-D` (force delete) + +## Output + +On success: +``` +Cleaned up: + Local: 3 branches deleted + Remote: 2 branches deleted + +Repository is tidy! +``` diff --git a/plugins/git-flow/commands/branch-start.md b/plugins/git-flow/commands/branch-start.md new file mode 100644 index 0000000..ceb099f --- /dev/null +++ b/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 +git pull origin + +# Create and switch to new branch +git checkout -b +``` + +### 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 +``` diff --git a/plugins/git-flow/commands/commit-merge.md b/plugins/git-flow/commands/commit-merge.md new file mode 100644 index 0000000..c019af5 --- /dev/null +++ b/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 + +# Pull latest +git pull origin + +# Merge feature branch +git merge [--squash] [--no-ff] + +# Push +git push origin +``` + +### 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 +``` diff --git a/plugins/git-flow/commands/commit-push.md b/plugins/git-flow/commands/commit-push.md new file mode 100644 index 0000000..6255ca2 --- /dev/null +++ b/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 ` +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 +``` diff --git a/plugins/git-flow/commands/commit-sync.md b/plugins/git-flow/commands/commit-sync.md new file mode 100644 index 0000000..57b2bcf --- /dev/null +++ b/plugins/git-flow/commands/commit-sync.md @@ -0,0 +1,79 @@ +# /commit-sync - Commit, Push, and Sync + +## Purpose + +Full sync operation: commit local changes, push to remote, and sync with upstream/base branch. + +## 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 +git fetch --all + +# Rebase on base branch +git rebase origin/ + +# Push again (if rebased) +git push --force-with-lease +``` + +### Step 4: 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. +``` + +## Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `GIT_DEFAULT_BASE` | `development` | Branch to sync with | +| `GIT_SYNC_STRATEGY` | `rebase` | How to incorporate upstream changes | + +## 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 +``` diff --git a/plugins/git-flow/commands/commit.md b/plugins/git-flow/commands/commit.md new file mode 100644 index 0000000..c0f1fce --- /dev/null +++ b/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: + +``` +(): + +[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' + + +Co-Authored-By: Claude +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(-) +``` diff --git a/plugins/git-flow/commands/git-config.md b/plugins/git-flow/commands/git-config.md new file mode 100644 index 0000000..2699da9 --- /dev/null +++ b/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. +``` diff --git a/plugins/git-flow/commands/git-status.md b/plugins/git-flow/commands/git-status.md new file mode 100644 index 0000000..8617443 --- /dev/null +++ b/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: +═══════════════════════════════════════════ + +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. diff --git a/plugins/git-flow/skills/workflow-patterns/branching-strategies.md b/plugins/git-flow/skills/workflow-patterns/branching-strategies.md new file mode 100644 index 0000000..560b247 --- /dev/null +++ b/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 + +``` +/ +``` + +### 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 + +``` +(): + +[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) +``` diff --git a/plugins/pr-review/.claude-plugin/plugin.json b/plugins/pr-review/.claude-plugin/plugin.json new file mode 100644 index 0000000..0073449 --- /dev/null +++ b/plugins/pr-review/.claude-plugin/plugin.json @@ -0,0 +1,71 @@ +{ + "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/support-claude-mktplace/src/branch/main/plugins/pr-review/README.md", + "repository": "https://gitea.hotserv.cloud/personal-projects/support-claude-mktplace.git", + "license": "MIT", + "keywords": [ + "pull-request", + "code-review", + "security", + "performance", + "multi-agent" + ], + "commands": [ + { + "name": "pr-review", + "description": "Full multi-agent PR review (security, performance, maintainability, tests)", + "file": "commands/pr-review.md" + }, + { + "name": "pr-summary", + "description": "Quick summary of PR changes without full review", + "file": "commands/pr-summary.md" + }, + { + "name": "pr-findings", + "description": "List and filter review findings by category or confidence", + "file": "commands/pr-findings.md" + } + ], + "agents": [ + { + "name": "coordinator", + "description": "Orchestrates the multi-agent review process", + "file": "agents/coordinator.md" + }, + { + "name": "security-reviewer", + "description": "Analyzes code for security vulnerabilities", + "file": "agents/security-reviewer.md" + }, + { + "name": "performance-analyst", + "description": "Identifies performance issues and optimization opportunities", + "file": "agents/performance-analyst.md" + }, + { + "name": "maintainability-auditor", + "description": "Reviews code quality, patterns, and maintainability", + "file": "agents/maintainability-auditor.md" + }, + { + "name": "test-validator", + "description": "Validates test coverage and test quality", + "file": "agents/test-validator.md" + } + ], + "skills": [ + { + "name": "review-patterns", + "description": "Code review patterns and confidence scoring rules", + "path": "skills/review-patterns" + } + ], + "mcpServers": ["gitea"] +} diff --git a/plugins/pr-review/.mcp.json b/plugins/pr-review/.mcp.json new file mode 100644 index 0000000..ef24980 --- /dev/null +++ b/plugins/pr-review/.mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "gitea": { + "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python", + "args": ["-m", "mcp_server.server"], + "cwd": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea" + } + } +} diff --git a/plugins/pr-review/README.md b/plugins/pr-review/README.md new file mode 100644 index 0000000..3d17a88 --- /dev/null +++ b/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 ` | Full multi-agent review | +| `/pr-summary ` | Quick summary without full review | +| `/pr-findings ` | 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 diff --git a/plugins/pr-review/agents/coordinator.md b/plugins/pr-review/agents/coordinator.md new file mode 100644 index 0000000..718484d --- /dev/null +++ b/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: # +═══════════════════════════════════════════════════ + +Summary: + Files changed: + Lines: + / - + Agents consulted: + +Findings: + 🔴 Critical: + 🟠 Major: + 🟡 Minor: + 💡 Suggestions: + +[Findings grouped by severity] + +─────────────────────────────────────────────────── +VERDICT: +─────────────────────────────────────────────────── + + +``` + +## 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 diff --git a/plugins/pr-review/agents/maintainability-auditor.md b/plugins/pr-review/agents/maintainability-auditor.md new file mode 100644 index 0000000..a5cc501 --- /dev/null +++ b/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 diff --git a/plugins/pr-review/agents/performance-analyst.md b/plugins/pr-review/agents/performance-analyst.md new file mode 100644 index 0000000..f8faff8 --- /dev/null +++ b/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 diff --git a/plugins/pr-review/agents/security-reviewer.md b/plugins/pr-review/agents/security-reviewer.md new file mode 100644 index 0000000..b9e9c41 --- /dev/null +++ b/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 diff --git a/plugins/pr-review/agents/test-validator.md b/plugins/pr-review/agents/test-validator.md new file mode 100644 index 0000000..1c67cca --- /dev/null +++ b/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 +``` diff --git a/plugins/pr-review/claude-md-integration.md b/plugins/pr-review/claude-md-integration.md new file mode 100644 index 0000000..87e235c --- /dev/null +++ b/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 ` | Full multi-agent review | +| `/pr-summary ` | Quick change summary | +| `/pr-findings ` | 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. diff --git a/plugins/pr-review/commands/pr-findings.md b/plugins/pr-review/commands/pr-findings.md new file mode 100644 index 0000000..2c2e136 --- /dev/null +++ b/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 [filters] +``` + +### Filters + +``` +--category Filter by category (security, performance, maintainability, tests) +--severity Filter by severity (critical, major, minor, suggestion) +--confidence Minimum confidence score (0.0-1.0) +--file 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 diff --git a/plugins/pr-review/commands/pr-review.md b/plugins/pr-review/commands/pr-review.md new file mode 100644 index 0000000..d899690 --- /dev/null +++ b/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 [--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 | diff --git a/plugins/pr-review/commands/pr-summary.md b/plugins/pr-review/commands/pr-summary.md new file mode 100644 index 0000000..dd00e89 --- /dev/null +++ b/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 [--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 diff --git a/plugins/pr-review/mcp-servers/gitea b/plugins/pr-review/mcp-servers/gitea new file mode 120000 index 0000000..e9b9ea7 --- /dev/null +++ b/plugins/pr-review/mcp-servers/gitea @@ -0,0 +1 @@ +../../../mcp-servers/gitea \ No newline at end of file diff --git a/plugins/pr-review/skills/review-patterns/confidence-scoring.md b/plugins/pr-review/skills/review-patterns/confidence-scoring.md new file mode 100644 index 0000000..5ef19b7 --- /dev/null +++ b/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) diff --git a/plugins/projman/CONFIGURATION.md b/plugins/projman/CONFIGURATION.md index b31667f..349f1a0 100644 --- a/plugins/projman/CONFIGURATION.md +++ b/plugins/projman/CONFIGURATION.md @@ -1,441 +1,39 @@ # Configuration Guide - Projman Plugin -Complete setup and configuration instructions for the Projman project management plugin. +For comprehensive configuration instructions, see the **[Centralized Configuration Guide](../../docs/CONFIGURATION.md)**. -## Overview +## Quick Reference -The Projman plugin uses a **hybrid configuration** approach: -- **System-level:** Credentials for Gitea (stored once per machine) -- **Project-level:** Repository path (stored per project) +### Required Configuration -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) +**System-level** (`~/.config/claude/gitea.env`): +```bash +GITEA_URL=https://gitea.example.com +GITEA_TOKEN=your_token +GITEA_ORG=your_organization +``` -## Prerequisites +**Project-level** (`.env` in project root): +```bash +GITEA_REPO=your-repo-name +``` -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/`: +### MCP Server Installation ```bash -# Navigate to MCP server directory (inside plugin) -cd plugins/projman/mcp-servers/gitea - -# Create virtual environment +cd mcp-servers/gitea 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 -``` - -## Step 2: Generate Gitea API Token - -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 +### Verification -**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 +/initial-setup +/labels-sync ``` -### 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! +For detailed setup instructions, troubleshooting, and security best practices, see [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md). diff --git a/plugins/projman/mcp-servers/gitea b/plugins/projman/mcp-servers/gitea new file mode 120000 index 0000000..e9b9ea7 --- /dev/null +++ b/plugins/projman/mcp-servers/gitea @@ -0,0 +1 @@ +../../../mcp-servers/gitea \ No newline at end of file diff --git a/scripts/post-update.sh b/scripts/post-update.sh index 75109a2..e8e9041 100755 --- a/scripts/post-update.sh +++ b/scripts/post-update.sh @@ -64,8 +64,9 @@ main() { echo "==============================================" echo "" + # Shared MCP servers at repository root (v3.0.0+) update_mcp_server "gitea" - update_mcp_server "wikijs" + update_mcp_server "netbox" check_changelog diff --git a/scripts/setup.sh b/scripts/setup.sh index 2ef84b5..e5c237a 100755 --- a/scripts/setup.sh +++ b/scripts/setup.sh @@ -1,17 +1,16 @@ #!/usr/bin/env bash # -# setup.sh - Initial setup for support-claude-mktplace +# setup.sh - Initial setup for lm-claude-plugins # # Usage: ./scripts/setup.sh # # This script: -# 1. Creates Python virtual environments for MCP servers (inside each plugin) +# 1. Creates Python virtual environments for MCP servers (shared at root) # 2. Installs dependencies # 3. Creates config file templates (if missing) # 4. Validates existing configuration -# 5. Checks/creates Wiki.js directory structure -# 6. Validates label reference file -# 7. Reports remaining manual steps +# 5. Validates label reference file +# 6. Reports remaining manual steps # set -euo pipefail @@ -40,13 +39,12 @@ log_error() { echo -e "${RED}[ERROR]${NC} $1"; FAILED+=("$1"); } log_todo() { echo -e "${YELLOW}[TODO]${NC} $1"; MANUAL_TODO+=("$1"); } # --- Section 1: Python Environments --- -# MCP servers are now inside each plugin -setup_plugin_mcp() { - local plugin_name="$1" - local server_name="$2" - local server_path="$REPO_ROOT/plugins/$plugin_name/mcp-servers/$server_name" +# MCP servers are now shared at repository root (v3.0.0+) +setup_shared_mcp() { + local server_name="$1" + local server_path="$REPO_ROOT/mcp-servers/$server_name" - log_info "Setting up $server_name MCP server (plugin: $plugin_name)..." + log_info "Setting up $server_name MCP server (shared)..." if [[ ! -d "$server_path" ]]; then log_error "$server_name directory not found at $server_path" @@ -57,10 +55,10 @@ setup_plugin_mcp() { # Check if venv exists if [[ -d ".venv" ]]; then - log_skip "$plugin_name/$server_name venv already exists" + log_skip "$server_name venv already exists" else python3 -m venv .venv - log_success "$plugin_name/$server_name venv created" + log_success "$server_name venv created" fi # Install/update dependencies @@ -69,15 +67,47 @@ setup_plugin_mcp() { pip install -q --upgrade pip pip install -q -r requirements.txt deactivate - log_success "$plugin_name/$server_name dependencies installed" + log_success "$server_name dependencies installed" else - log_error "$plugin_name/$server_name requirements.txt not found" + log_error "$server_name requirements.txt not found" fi cd "$REPO_ROOT" } -# --- Section 2: Config File Templates --- +# --- Section 2: Verify Symlinks --- +verify_symlinks() { + log_info "Verifying MCP server symlinks..." + + # Check projman -> gitea symlink + local projman_gitea="$REPO_ROOT/plugins/projman/mcp-servers/gitea" + if [[ -L "$projman_gitea" ]]; then + log_success "projman/gitea symlink exists" + else + log_error "projman/gitea symlink missing" + log_todo "Run: ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea" + fi + + # Check cmdb-assistant -> netbox symlink + local cmdb_netbox="$REPO_ROOT/plugins/cmdb-assistant/mcp-servers/netbox" + if [[ -L "$cmdb_netbox" ]]; then + log_success "cmdb-assistant/netbox symlink exists" + else + log_error "cmdb-assistant/netbox symlink missing" + log_todo "Run: ln -s ../../../mcp-servers/netbox plugins/cmdb-assistant/mcp-servers/netbox" + fi + + # Check pr-review -> gitea symlink + local prreview_gitea="$REPO_ROOT/plugins/pr-review/mcp-servers/gitea" + if [[ -L "$prreview_gitea" ]]; then + log_success "pr-review/gitea symlink exists" + else + log_error "pr-review/gitea symlink missing" + log_todo "Run: ln -s ../../../mcp-servers/gitea plugins/pr-review/mcp-servers/gitea" + fi +} + +# --- Section 3: Config File Templates --- setup_config_templates() { local config_dir="$HOME/.config/claude" @@ -94,32 +124,15 @@ setup_config_templates() { # Gitea API Configuration # Update these values with your Gitea instance details -GITEA_API_URL=https://gitea.example.com/api/v1 -GITEA_API_TOKEN=your_gitea_token_here -GITEA_OWNER=your_organization_name +GITEA_URL=https://gitea.example.com +GITEA_TOKEN=your_gitea_token_here +GITEA_ORG=your_organization_name EOF chmod 600 "$config_dir/gitea.env" log_success "gitea.env template created" log_todo "Edit ~/.config/claude/gitea.env with your Gitea credentials" fi - # Wiki.js config - if [[ -f "$config_dir/wikijs.env" ]]; then - log_skip "wikijs.env already exists" - else - cat > "$config_dir/wikijs.env" << 'EOF' -# Wiki.js API Configuration -# Update these values with your Wiki.js instance details - -WIKIJS_API_URL=https://wiki.example.com/graphql -WIKIJS_API_TOKEN=your_wikijs_jwt_token_here -WIKIJS_BASE_PATH=/your-namespace -EOF - chmod 600 "$config_dir/wikijs.env" - log_success "wikijs.env template created" - log_todo "Edit ~/.config/claude/wikijs.env with your Wiki.js credentials" - fi - # NetBox config if [[ -f "$config_dir/netbox.env" ]]; then log_skip "netbox.env already exists" @@ -128,16 +141,35 @@ EOF # NetBox API Configuration # Update these values with your NetBox instance details -NETBOX_API_URL=https://netbox.example.com/api -NETBOX_API_TOKEN=your_netbox_token_here +NETBOX_URL=https://netbox.example.com +NETBOX_TOKEN=your_netbox_token_here EOF chmod 600 "$config_dir/netbox.env" log_success "netbox.env template created" log_todo "Edit ~/.config/claude/netbox.env with your NetBox credentials" fi + + # Git-flow config (optional) + if [[ -f "$config_dir/git-flow.env" ]]; then + log_skip "git-flow.env already exists" + else + cat > "$config_dir/git-flow.env" << 'EOF' +# Git-Flow Default Configuration (optional) + +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 +EOF + chmod 600 "$config_dir/git-flow.env" + log_success "git-flow.env template created" + fi } -# --- Section 3: Validate Configuration --- +# --- Section 4: Validate Configuration --- validate_config() { local config_dir="$HOME/.config/claude" @@ -146,53 +178,24 @@ validate_config() { # Check Gitea config has real values if [[ -f "$config_dir/gitea.env" ]]; then source "$config_dir/gitea.env" - if [[ "${GITEA_API_TOKEN:-}" == "your_gitea_token_here" ]] || [[ -z "${GITEA_API_TOKEN:-}" ]]; then - log_todo "Update GITEA_API_TOKEN in ~/.config/claude/gitea.env" + if [[ "${GITEA_TOKEN:-}" == "your_gitea_token_here" ]] || [[ -z "${GITEA_TOKEN:-}" ]]; then + log_todo "Update GITEA_TOKEN in ~/.config/claude/gitea.env" else log_success "Gitea configuration appears valid" fi fi - # Check Wiki.js config has real values - if [[ -f "$config_dir/wikijs.env" ]]; then - source "$config_dir/wikijs.env" - if [[ "${WIKIJS_API_TOKEN:-}" == "your_wikijs_jwt_token_here" ]] || [[ -z "${WIKIJS_API_TOKEN:-}" ]]; then - log_todo "Update WIKIJS_API_TOKEN in ~/.config/claude/wikijs.env" - else - log_success "Wiki.js configuration appears valid" - fi - fi - # Check NetBox config has real values if [[ -f "$config_dir/netbox.env" ]]; then source "$config_dir/netbox.env" - if [[ "${NETBOX_API_TOKEN:-}" == "your_netbox_token_here" ]] || [[ -z "${NETBOX_API_TOKEN:-}" ]]; then - log_todo "Update NETBOX_API_TOKEN in ~/.config/claude/netbox.env" + if [[ "${NETBOX_TOKEN:-}" == "your_netbox_token_here" ]] || [[ -z "${NETBOX_TOKEN:-}" ]]; then + log_todo "Update NETBOX_TOKEN in ~/.config/claude/netbox.env" else log_success "NetBox configuration appears valid" fi fi } -# --- Section 4: Wiki.js Directory Structure --- -setup_wikijs_structure() { - log_info "Wiki.js directory structure check..." - - # This requires Wiki.js MCP to be working - # For now, just note it as a TODO if credentials aren't set - - local config_dir="$HOME/.config/claude" - if [[ -f "$config_dir/wikijs.env" ]]; then - source "$config_dir/wikijs.env" - if [[ "${WIKIJS_API_TOKEN:-}" != "your_wikijs_jwt_token_here" ]] && [[ -n "${WIKIJS_API_TOKEN:-}" ]]; then - log_info "Wiki.js credentials found - directory structure can be verified after first use" - log_success "Wiki.js setup deferred to first use" - else - log_todo "Configure Wiki.js credentials, then verify directory structure exists" - fi - fi -} - # --- Section 5: Label Sync --- # Note: This requires Gitea MCP to be functional # For initial setup, we just validate the label reference file exists @@ -262,24 +265,21 @@ print_report() { # --- Main --- main() { echo "==============================================" - echo " support-claude-mktplace Setup" + echo " lm-claude-plugins Setup (v3.0.0)" echo "==============================================" echo "" - # Python environments for projman plugin - setup_plugin_mcp "projman" "gitea" - setup_plugin_mcp "projman" "wikijs" + # Shared MCP servers at repository root + setup_shared_mcp "gitea" + setup_shared_mcp "netbox" - # Python environment for cmdb-assistant plugin - setup_plugin_mcp "cmdb-assistant" "netbox" + # Verify symlinks from plugins to shared MCP servers + verify_symlinks # Configuration setup_config_templates validate_config - # Wiki.js structure - setup_wikijs_structure - # Labels setup_labels diff --git a/scripts/validate-marketplace.sh b/scripts/validate-marketplace.sh index 876d994..7218a7b 100755 --- a/scripts/validate-marketplace.sh +++ b/scripts/validate-marketplace.sh @@ -73,6 +73,22 @@ for i in $(seq 0 $((PLUGIN_COUNT - 1))); do echo "WARNING: Missing 'repository' in marketplace entry for $PLUGIN_NAME" fi + # v3.0.0: Check category, tags, license fields + if ! jq -e ".plugins[$i].category" "$MARKETPLACE_JSON" >/dev/null; then + echo "ERROR: Missing 'category' in marketplace entry for $PLUGIN_NAME (required v3.0.0+)" + exit 1 + fi + + if ! jq -e ".plugins[$i].tags | type == \"array\"" "$MARKETPLACE_JSON" >/dev/null; then + echo "ERROR: Missing or invalid 'tags' array in marketplace entry for $PLUGIN_NAME (required v3.0.0+)" + exit 1 + fi + + if ! jq -e ".plugins[$i].license" "$MARKETPLACE_JSON" >/dev/null; then + echo "ERROR: Missing 'license' in marketplace entry for $PLUGIN_NAME (required v3.0.0+)" + exit 1 + fi + echo "✓ Marketplace entry $PLUGIN_NAME valid" done @@ -135,5 +151,49 @@ for plugin_dir in "$PLUGINS_DIR"/*/; do echo "✓ $plugin_name valid" done +# v3.0.0: Validate MCP server symlinks +echo "" +echo "=== Validating MCP Server Symlinks (v3.0.0+) ===" + +# Check shared MCP servers exist +if [[ ! -d "$ROOT_DIR/mcp-servers/gitea" ]]; then + echo "ERROR: Shared gitea MCP server not found at mcp-servers/gitea/" + exit 1 +fi +echo "✓ Shared gitea MCP server exists" + +if [[ ! -d "$ROOT_DIR/mcp-servers/netbox" ]]; then + echo "ERROR: Shared netbox MCP server not found at mcp-servers/netbox/" + exit 1 +fi +echo "✓ Shared netbox MCP server exists" + +# Check symlinks for plugins that use MCP servers +check_mcp_symlink() { + local plugin_name="$1" + local server_name="$2" + local symlink_path="$ROOT_DIR/plugins/$plugin_name/mcp-servers/$server_name" + + if [[ -L "$symlink_path" ]]; then + # Verify symlink resolves correctly + if [[ -d "$symlink_path" ]]; then + echo "✓ $plugin_name -> $server_name symlink valid" + else + echo "ERROR: $plugin_name -> $server_name symlink broken (does not resolve)" + exit 1 + fi + else + echo "ERROR: Missing symlink at plugins/$plugin_name/mcp-servers/$server_name" + exit 1 + fi +} + +# Plugins with gitea MCP dependency +check_mcp_symlink "projman" "gitea" +check_mcp_symlink "pr-review" "gitea" + +# Plugins with netbox MCP dependency +check_mcp_symlink "cmdb-assistant" "netbox" + echo "" echo "=== All validations passed ===" From 39ad0043c6a64ee16fd746255ef19bd02d1a1f7c Mon Sep 17 00:00:00 2001 From: lmiranda Date: Tue, 20 Jan 2026 17:01:25 -0500 Subject: [PATCH 2/2] fix: bump projman version to 3.0.0 Co-Authored-By: Claude Opus 4.5 --- plugins/projman/.claude-plugin/plugin.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/projman/.claude-plugin/plugin.json b/plugins/projman/.claude-plugin/plugin.json index 2e2fa31..968c7d9 100644 --- a/plugins/projman/.claude-plugin/plugin.json +++ b/plugins/projman/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "projman", - "version": "2.3.0", + "version": "3.0.0", "description": "Sprint planning and project management with Gitea integration", "author": { "name": "Leo Miranda",