diff --git a/plugins/projman/CONFIGURATION.md b/plugins/projman/CONFIGURATION.md index 300060b..0d3e7c4 100644 --- a/plugins/projman/CONFIGURATION.md +++ b/plugins/projman/CONFIGURATION.md @@ -1,18 +1,18 @@ -# Configuration Guide - Projman Plugin +# Configuration Guide - Projman Plugin v1.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 and Wiki.js (stored once per machine) -- **Project-level:** Repository and project paths (stored per project) +- **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) +- 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 @@ -20,7 +20,7 @@ Before configuring the plugin, ensure you have: 1. **Python 3.10+** installed ```bash - python --version # Should be 3.10.0 or higher + python3 --version # Should be 3.10.0 or higher ``` 2. **Git repository** initialized @@ -32,26 +32,20 @@ Before configuring the plugin, ensure you have: - Create issues - Manage labels - Read organization information + - Access repository wiki -4. **Wiki.js access** with an account and permissions to: - - Create and edit pages - - Manage tags - - Read and write content +4. **Claude Code** installed and working -5. **Claude Code** installed and working +## Step 1: Install MCP Server -## 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 +The plugin bundles the Gitea MCP server at `mcp-servers/gitea/`: ```bash -# Navigate to Gitea MCP server directory -cd ../mcp-servers/gitea +# Navigate to MCP server directory (inside plugin) +cd plugins/projman/mcp-servers/gitea # Create virtual environment -python -m venv .venv +python3 -m venv .venv # Activate virtual environment source .venv/bin/activate # Linux/Mac @@ -63,32 +57,12 @@ pip install -r requirements.txt # Verify installation python -c "from mcp_server import server; print('Gitea MCP Server installed successfully')" + +# Deactivate when done +deactivate ``` -### 1.2 Install Wiki.js MCP Server - -```bash -# 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 +## Step 2: Generate Gitea API Token 1. Log into Gitea: https://gitea.example.com 2. Navigate to: **User Icon** (top right) → **Settings** @@ -98,41 +72,23 @@ python -c "from mcp_server import server; print('Wiki.js MCP Server installed su 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 + - `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 and labels +- `repo` - Create, read, update issues, labels, and wiki - `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.your-company.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 +- `write:repo` - Create wiki pages for lessons learned ## Step 3: System-Level Configuration -Create system-wide configuration files in `~/.config/claude/`: +Create system-wide configuration file in `~/.config/claude/`: ### 3.1 Create Configuration Directory @@ -145,55 +101,35 @@ mkdir -p ~/.config/claude ```bash 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 +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 `your_gitea_token_here` with the token from Step 2.1** +**Replace placeholders:** +- `your_gitea_token_here` with the token from Step 2 +- `your_organization` with your Gitea organization name **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`) +- `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 Configure Wiki.js +### 3.3 Verify System Configuration ```bash -cat > ~/.config/claude/wikijs.env << 'EOF' -# Wiki.js API Configuration -WIKIJS_API_URL=https://wiki.your-company.com/graphql -WIKIJS_API_TOKEN=your_wikijs_token_here -WIKIJS_BASE_PATH=/your-org -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., `/your-org`) - -### 3.4 Verify System Configuration - -```bash -# Check files exist and have correct permissions -ls -la ~/.config/claude/ +# Check file exists and has correct permissions +ls -la ~/.config/claude/gitea.env # Should show: # -rw------- gitea.env -# -rw------- wikijs.env ``` -**Security Note:** Files should have `600` permissions (owner read/write only) to protect API tokens. +**Security Note:** File should have `600` permissions (owner read/write only) to protect API tokens. ## Step 4: Project-Level Configuration @@ -206,42 +142,28 @@ For each project where you'll use Projman, create a `.env` file: 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:** +**Example for MyProject:** ```bash cat > .env << 'EOF' -GITEA_REPO=cuisineflow -WIKIJS_PROJECT=projects/cuisineflow +GITEA_REPO=my-project EOF ``` -### 4.2 Add .env to .gitignore - -**CRITICAL:** Never commit `.env` to git! - -```bash -# Add to .gitignore -echo ".env" >> .gitignore - -# Verify -git check-ignore .env # Should output: .env -``` - -### 4.3 Verify Project Configuration +### 4.2 Verify Project Configuration ```bash # Check .env exists ls -la .env -# Check it's in .gitignore -cat .gitignore | grep "\.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: @@ -256,23 +178,21 @@ curl -H "Authorization: token YOUR_GITEA_TOKEN" \ # Should return your user information in JSON format ``` -### 5.2 Test Wiki.js Connection +### 5.2 Test Wiki Access ```bash -# Test GraphQL endpoint -curl -H "Authorization: Bearer YOUR_WIKIJS_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"query": "{ pages { list { id title } } }"}' \ - https://wiki.your-company.com/graphql +# 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 pages data in JSON format +# Should return list of wiki pages (or empty array) ``` ### 5.3 Test MCP Server Loading ```bash # Navigate to plugin directory -cd projman +cd plugins/projman # Verify .mcp.json exists cat .mcp.json @@ -283,9 +203,19 @@ claude --debug ## Step 6: Initialize Plugin -### 6.1 Sync Label Taxonomy +### 6.1 Run Initial Setup -First time setup - fetch labels from Gitea: +```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 @@ -296,15 +226,16 @@ This will: - Update `skills/label-taxonomy/labels-reference.md` - Enable intelligent label suggestions -### 6.2 Verify Commands Available +### 6.3 Verify Commands Available ```bash # List available commands -/sprint-plan --help -/sprint-start --help -/sprint-status --help -/sprint-close --help -/labels-sync --help +/sprint-plan +/sprint-start +/sprint-status +/sprint-close +/labels-sync +/initial-setup ``` ## Configuration Files Reference @@ -313,16 +244,9 @@ This will: **`~/.config/claude/gitea.env`:** ```bash -GITEA_API_URL=https://gitea.example.com/api/v1 -GITEA_API_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx -GITEA_OWNER=bandit -``` - -**`~/.config/claude/wikijs.env`:** -```bash -WIKIJS_API_URL=https://wiki.your-company.com/graphql -WIKIJS_API_TOKEN=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... -WIKIJS_BASE_PATH=/your-org +GITEA_URL=https://gitea.example.com +GITEA_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxxx +GITEA_ORG=your_organization ``` ### Project-Level Files @@ -330,12 +254,6 @@ WIKIJS_BASE_PATH=/your-org **`.env` (in project root):** ```bash GITEA_REPO=your-repo-name -WIKIJS_PROJECT=projects/your-project-name -``` - -**`.gitignore` (must include):** -``` -.env ``` ### Plugin Configuration @@ -345,19 +263,11 @@ WIKIJS_PROJECT=projects/your-project-name { "mcpServers": { "gitea": { - "command": "python", + "command": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python", "args": ["-m", "mcp_server.server"], - "cwd": "${CLAUDE_PLUGIN_ROOT}/../mcp-servers/gitea", + "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" + "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea" } } } @@ -375,24 +285,21 @@ To use Projman with multiple projects: ```bash # ~/projects/my-app/.env GITEA_REPO=my-app -WIKIJS_PROJECT=projects/my-app ``` **Project 2: App Site** ```bash # ~/projects/my-app-site/.env GITEA_REPO=my-app-site -WIKIJS_PROJECT=projects/my-app-site ``` **Project 3: Company Site** ```bash # ~/projects/company-site/.env GITEA_REPO=company-site -WIKIJS_PROJECT=projects/company-site ``` -Each project operates independently with its own issues and lessons learned. +Each project operates independently with its own issues and lessons learned (stored in each repository's wiki). ## Troubleshooting @@ -404,7 +311,6 @@ Each project operates independently with its own issues and lessons learned. ```bash # Check system config exists ls -la ~/.config/claude/gitea.env -ls -la ~/.config/claude/wikijs.env # If missing, recreate from Step 3 ``` @@ -419,10 +325,6 @@ ls -la ~/.config/claude/wikijs.env 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.your-company.com/graphql - # If fails, regenerate token (Step 2) ``` @@ -433,13 +335,12 @@ curl -H "Authorization: Bearer YOUR_TOKEN" \ **Solution:** ```bash # Check Python virtual environment exists -ls ../mcp-servers/gitea/.venv -ls ../mcp-servers/wikijs/.venv +ls plugins/projman/mcp-servers/gitea/.venv # If missing, reinstall (Step 1) # Check dependencies installed -cd ../mcp-servers/gitea +cd plugins/projman/mcp-servers/gitea source .venv/bin/activate python -c "import requests; import mcp" @@ -447,35 +348,41 @@ python -c "import requests; import mcp" pip install -r requirements.txt ``` -### Wrong repository or project +### Wrong repository -**Problem:** Issues created in wrong repo or lessons saved to wrong project +**Problem:** Issues created in wrong repo **Solution:** ```bash # Check project .env configuration cat .env -# Verify GITEA_REPO matches Gitea repository name -# Verify WIKIJS_PROJECT matches Wiki.js project path +# Verify GITEA_REPO matches Gitea repository name exactly # Update if incorrect -nano .env ``` ### Permissions errors -**Problem:** "Permission denied" when creating issues or pages +**Problem:** "Permission denied" when creating issues or wiki 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 +- 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 `.env` in `.gitignore` + - Keep credentials in `~/.config/claude/` only - Never hardcode tokens in code - Use system-level config for credentials @@ -491,51 +398,43 @@ nano .env 4. **Minimum permissions** - Only grant required permissions - - Gitea: `repo`, `read:org`, `read:user` - - Wiki.js: Pages (read/create/update), Search (read) + - Gitea: `repo`, `read:org`, `read:user`, `write:repo` 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](./README.md) for usage guide -4. ✅ Review command documentation in `commands/` +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 -- Review MCP server documentation: - - [Gitea MCP](../mcp-servers/gitea/README.md) - - [Wiki.js MCP](../mcp-servers/wikijs/README.md) - Contact repository maintainer for support **Questions:** - Read command documentation: `commands/*.md` -- Check agent descriptions in `agents/` (Phase 3) -- Review skills: `skills/label-taxonomy/` +- Check agent descriptions in `agents/` --- **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`) +- [ ] 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`) -- [ ] `.env` added to `.gitignore` - [ ] Gitea connection tested -- [ ] Wiki.js connection tested +- [ ] Wiki access tested +- [ ] `/initial-setup` completed successfully - [ ] `/labels-sync` completed successfully - [ ] Commands verified available