leo-claude-mktplace/plugins/projman/CONFIGURATION.md

Configuration Guide - Projman Plugin v2.0.0

Complete setup and configuration instructions for the Projman project management plugin.

Overview

The Projman plugin uses a hybrid configuration approach:

• System-level: Credentials for Gitea (stored once per machine)
• Project-level: Repository path (stored per project)

This design allows:

• Single token per service (update once, use everywhere)
• Easy multi-project setup (just add .env per project)
• Security (tokens never committed to git)
• Project isolation (each project has its own scope)

Prerequisites

Before configuring the plugin, ensure you have:

1. Python 3.10+ installed

   python3 --version  # Should be 3.10.0 or higher
   

2. Git repository initialized

   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/:

# Navigate to MCP server directory (inside plugin)
cd plugins/projman/mcp-servers/gitea

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # Linux/Mac
# or
.venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt

# Verify installation
python -c "from mcp_server import server; print('Gitea MCP Server installed successfully')"

# Deactivate when done
deactivate

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

mkdir -p ~/.config/claude

3.2 Configure Gitea

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

# 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

# In your project root directory
cat > .env << 'EOF'
# Gitea Repository Configuration
GITEA_REPO=your-repo-name
EOF

Example for MyProject:

cat > .env << 'EOF'
GITEA_REPO=my-project
EOF

4.2 Verify Project Configuration

# 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

# 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

# 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

# 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

/initial-setup

This will:

• Validate Gitea MCP server connection
• Test credential configuration
• Sync label taxonomy
• Verify required directory structure

6.2 Sync Label Taxonomy

/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

# 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:

GITEA_URL=https://gitea.example.com
GITEA_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx
GITEA_ORG=your_organization

Project-Level Files

.env (in project root):

GITEA_REPO=your-repo-name

Plugin Configuration

projman/.mcp.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

# ~/projects/my-app/.env
GITEA_REPO=my-app

Project 2: App Site

# ~/projects/my-app-site/.env
GITEA_REPO=my-app-site

Project 3: Company Site

# ~/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:

# 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:

# 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:

# Check Python virtual environment exists
ls plugins/projman/mcp-servers/gitea/.venv

# If missing, reinstall (Step 1)

# Check dependencies installed
cd plugins/projman/mcp-servers/gitea
source .venv/bin/activate
python -c "import requests; import mcp"

# If import fails, reinstall requirements
pip install -r requirements.txt

Wrong repository

Problem: Issues created in wrong repo

Solution:

# Check project .env configuration
cat .env

# Verify GITEA_REPO matches Gitea repository name exactly

# Update if incorrect

Permissions errors

Problem: "Permission denied" when creating issues or wiki pages

Solution:

• Verify token has repo, read:org, and write:repo permissions (Step 2)
• Regenerate token with correct permissions if needed

Repository not in organization

Problem: "Repository must belong to configured organization"

Solution:

• Verify GITEA_ORG in system config matches the organization owning the repository
• Verify GITEA_REPO belongs to that organization
• Fork the repository to your organization if needed

Security Best Practices

1. Never commit tokens

   • Keep credentials in ~/.config/claude/ only
   • Never hardcode tokens in code
   • Use system-level config for credentials

2. Secure configuration files

   • Set 600 permissions on ~/.config/claude/*.env
   • Store in user home directory only
   • Don't share token files

3. Rotate tokens periodically

   • Regenerate tokens every 6-12 months
   • Immediately revoke if compromised
   • Use separate tokens for dev/prod if needed

4. Minimum permissions

   • Only grant required permissions
   • Gitea: repo, read:org, read:user, write:repo

5. Monitor usage

   • Review Gitea access logs periodically
   • Watch for unexpected API usage

Next Steps

After configuration is complete:

1. Run /initial-setup to verify everything works
2. Run /labels-sync to fetch label taxonomy
3. Try /sprint-plan to start your first sprint
4. Read README.md for usage guide

Support

Configuration Issues:

• Check 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!