leo-claude-mktplace/projman/CONFIGURATION.md

Configuration Guide - Projman Plugin

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 and Wiki.js (stored once per machine)
• Project-level: Repository and project paths (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

   python --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

4. Wiki.js access with an account and permissions to:

   • Create and edit pages
   • Manage tags
   • Read and write content

5. Claude Code installed and working

Step 1: Install MCP Servers

The plugin requires two MCP servers installed at ../mcp-servers/ relative to the plugin:

1.1 Install Gitea MCP Server

# Navigate to Gitea MCP server directory
cd ../mcp-servers/gitea

# Create virtual environment
python -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')"

1.2 Install Wiki.js MCP Server

# Navigate to Wiki.js MCP server directory
cd ../mcp-servers/wikijs

# Create virtual environment
python -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('Wiki.js MCP Server installed successfully')"

Step 2: Generate API Tokens

2.1 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
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 and labels
• read:org - Access organization-level labels
• read:user - Associate issues with user account

2.2 Generate Wiki.js API Token

1. Log into Wiki.js: https://wiki.hyperhivelabs.com
2. Navigate to: Administration (top right)
3. Click API Access in the left sidebar
4. Click New API Key
5. Configure API key:
   • Name: claude-code-projman
   • Expiration: None (or set to your security policy)
   • Permissions:
     • ✅ Pages: Read, Create, Update
     • ✅ Search: Read
6. Click Create
7. IMPORTANT: Copy the JWT token immediately (shown only once!)
8. Save token securely - you'll need it in Step 3

Token Permissions Explained:

• Pages (read/create/update) - Manage documentation and lessons learned
• Search (read) - Find relevant lessons from previous sprints

Step 3: System-Level Configuration

Create system-wide configuration files 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_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=your_gitea_token_here
GITEA_OWNER=bandit
EOF

# Secure the file (owner read/write only)
chmod 600 ~/.config/claude/gitea.env

Replace your_gitea_token_here with the token from Step 2.1

Configuration Variables:

• GITEA_API_URL - Gitea API endpoint (includes /api/v1)
• GITEA_API_TOKEN - Personal access token from Step 2.1
• GITEA_OWNER - Organization or user name (e.g., bandit)

3.3 Configure Wiki.js

cat > ~/.config/claude/wikijs.env << 'EOF'
# Wiki.js API Configuration
WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql
WIKIJS_API_TOKEN=your_wikijs_token_here
WIKIJS_BASE_PATH=/hyper-hive-labs
EOF

# Secure the file (owner read/write only)
chmod 600 ~/.config/claude/wikijs.env

Replace your_wikijs_token_here with the JWT token from Step 2.2

Configuration Variables:

• WIKIJS_API_URL - Wiki.js GraphQL endpoint (includes /graphql)
• WIKIJS_API_TOKEN - API key from Step 2.2 (JWT format)
• WIKIJS_BASE_PATH - Base path in Wiki.js (e.g., /hyper-hive-labs)

3.4 Verify System Configuration

# Check files exist and have correct permissions
ls -la ~/.config/claude/

# Should show:
# -rw------- gitea.env
# -rw------- wikijs.env

Security Note: Files 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

# Wiki.js Project Configuration
WIKIJS_PROJECT=projects/your-project-name
EOF

Example for CuisineFlow project:

cat > .env << 'EOF'
GITEA_REPO=cuisineflow
WIKIJS_PROJECT=projects/cuisineflow
EOF

4.2 Add .env to .gitignore

CRITICAL: Never commit .env to git!

# Add to .gitignore
echo ".env" >> .gitignore

# Verify
git check-ignore .env  # Should output: .env

4.3 Verify Project Configuration

# Check .env exists
ls -la .env

# Check it's in .gitignore
cat .gitignore | grep "\.env"

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.js Connection

# Test GraphQL endpoint
curl -H "Authorization: Bearer YOUR_WIKIJS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ pages { list { id title } } }"}' \
  https://wiki.hyperhivelabs.com/graphql

# Should return pages data in JSON format

5.3 Test MCP Server Loading

# Navigate to plugin directory
cd 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 Sync Label Taxonomy

First time setup - fetch labels from Gitea:

/labels-sync

This will:

• Fetch all labels from Gitea (organization + repository)
• Update skills/label-taxonomy/labels-reference.md
• Enable intelligent label suggestions

6.2 Verify Commands Available

# List available commands
/sprint-plan --help
/sprint-start --help
/sprint-status --help
/sprint-close --help
/labels-sync --help

Configuration Files Reference

System-Level Files

~/.config/claude/gitea.env:

GITEA_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx
GITEA_OWNER=bandit

~/.config/claude/wikijs.env:

WIKIJS_API_URL=https://wiki.hyperhivelabs.com/graphql
WIKIJS_API_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
WIKIJS_BASE_PATH=/hyper-hive-labs

Project-Level Files

.env (in project root):

GITEA_REPO=cuisineflow
WIKIJS_PROJECT=projects/cuisineflow

.gitignore (must include):

.env

Plugin Configuration

projman/.mcp.json:

{
  "mcpServers": {
    "gitea": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea",
      "env": {
        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea"
      }
    },
    "wikijs": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs",
      "env": {
        "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/wikijs"
      }
    }
  }
}

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

# ~/projects/cuisineflow/.env
GITEA_REPO=cuisineflow
WIKIJS_PROJECT=projects/cuisineflow

Project 2: CuisineFlow-Site

# ~/projects/cuisineflow-site/.env
GITEA_REPO=cuisineflow-site
WIKIJS_PROJECT=projects/cuisineflow-site

Project 3: HHL-Site

# ~/projects/hhl-site/.env
GITEA_REPO=hhl-site
WIKIJS_PROJECT=projects/hhl-site

Each project operates independently with its own issues and lessons learned.

Troubleshooting

Cannot find configuration files

Problem: MCP server reports "Configuration not found"

Solution:

# Check system config exists
ls -la ~/.config/claude/gitea.env
ls -la ~/.config/claude/wikijs.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

# Test Wiki.js token
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://wiki.hyperhivelabs.com/graphql

# If fails, regenerate token (Step 2)

MCP server not starting

Problem: "Failed to start MCP server"

Solution:

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

# If missing, reinstall (Step 1)

# Check dependencies installed
cd ../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 or project

Problem: Issues created in wrong repo or lessons saved to wrong project

Solution:

# Check project .env configuration
cat .env

# Verify GITEA_REPO matches Gitea repository name
# Verify WIKIJS_PROJECT matches Wiki.js project path

# Update if incorrect
nano .env

Permissions errors

Problem: "Permission denied" when creating issues or pages

Solution:

• Gitea: Verify token has repo and read:org permissions (Step 2.1)
• Wiki.js: Verify token has Pages (create/update) permissions (Step 2.2)
• Regenerate tokens with correct permissions if needed

Security Best Practices

1. Never commit tokens

   • Keep .env in .gitignore
   • 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
   • Wiki.js: Pages (read/create/update), Search (read)

5. Monitor usage

   • Review Gitea access logs periodically
   • Check Wiki.js audit logs
   • Watch for unexpected API usage

Next Steps

After configuration is complete:

1. ✅ Run /labels-sync to fetch label taxonomy
2. ✅ Try /sprint-plan to start your first sprint
3. ✅ Read README.md for usage guide
4. ✅ Review command documentation in commands/

Support

Configuration Issues:

• Check README.md troubleshooting section
• Review MCP server documentation:
  • Gitea MCP
  • Wiki.js MCP
• Contact repository maintainer for support

Questions:

• Read command documentation: commands/*.md
• Check agent descriptions in agents/ (Phase 3)
• Review skills: skills/label-taxonomy/

---

Configuration Status Checklist:

• Python 3.10+ installed
• Gitea MCP server installed
• Wiki.js MCP server installed
• Gitea API token generated
• Wiki.js API token generated
• System config created (~/.config/claude/*.env)
• Project config created (.env)
• .env added to .gitignore
• Gitea connection tested
• Wiki.js connection tested
• /labels-sync completed successfully
• Commands verified available

Once all items are checked, you're ready to use Projman!