personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: v3.0.0 architecture overhaul

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-20 16:56:53 -05:00
parent c1e9382031
commit e5ca804692
81 changed files with 4747 additions and 705 deletions
Download Patch File Download Diff File Expand all files Collapse all files

440
plugins/projman/CONFIGURATION.md
View File

@@ -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).