2026-01-19 22:23:28 +00:00
1 changed files with 107 additions and 208 deletions
--- 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