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

development #54

Merged
lmiranda merged 2 commits from development into main 2026-01-21 16:24:26 +00:00
Conversation 0 Commits 2 Files Changed 16 +2132 -401
16 changed files with 2132 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 2a6b3df8e1 - Show all commits

23
CLAUDE.md
View File

@@ -28,7 +28,12 @@ A plugin marketplace for Claude Code containing:
# Validate marketplace compliance
./scripts/validate-marketplace.sh
# Run projman commands (in a target project with plugin installed)
# Setup commands (in a target project with plugin installed)
/initial-setup # First time: full setup wizard
/project-init # New project: quick config
/project-sync # After repo move: sync config
# Run projman commands
/sprint-plan # Start sprint planning
/sprint-status # Check progress
/review # Pre-close code quality review
@@ -50,18 +55,20 @@ leo-claude-mktplace/
│ │ ├── .claude-plugin/plugin.json
│ │ ├── .mcp.json
│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK
│ │ ├── commands/ # 9 commands
│ │ ├── commands/ # 12 commands (incl. setup)
│ │ ├── hooks/ # SessionStart mismatch detection
│ │ ├── agents/ # 4 agents
│ │ └── skills/label-taxonomy/
│ ├── git-flow/ # Git workflow automation (NEW v3.0.0)
│ ├── git-flow/ # Git workflow automation
│ │ ├── .claude-plugin/plugin.json
│ │ ├── commands/ # 8 commands
│ │ └── agents/
│ ├── pr-review/ # Multi-agent PR review (NEW v3.0.0)
│ ├── pr-review/ # Multi-agent PR review
│ │ ├── .claude-plugin/plugin.json
│ │ ├── .mcp.json
│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK
│ │ ├── commands/ # 3 commands
│ │ ├── commands/ # 6 commands (incl. setup)
│ │ ├── hooks/ # SessionStart mismatch detection
│ │ └── agents/ # 5 agents
│ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0)
│ │ ├── .claude-plugin/plugin.json
@@ -133,8 +140,10 @@ leo-claude-mktplace/
| Level | Location | Purpose |
|-------|----------|---------|
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) |
| Project | `.env` in project root | Repository specification (GITEA_REPO) |
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN) |
| Project | `.env` in project root | Repository specification (GITEA_ORG, GITEA_REPO) |
**Note:** `GITEA_ORG` is at project level since different projects may belong to different organizations.
### Branch-Aware Security

38
docs/COMMANDS-CHEATSHEET.md
View File

@@ -15,7 +15,10 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
| **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
| **projman** | `/initial-setup` | | X | Run installation script for projman plugin setup |
| **projman** | `/initial-setup` | | X | Full setup wizard: MCP server + system config + project config |
| **projman** | `/project-init` | | X | Quick project setup (assumes system config exists) |
| **projman** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run /project-sync |
| **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
| **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
| **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation |
@@ -25,6 +28,10 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **git-flow** | `/branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
| **git-flow** | `/git-status` | | X | Enhanced git status with recommendations |
| **git-flow** | `/git-config` | | X | Configure git-flow settings for the project |
| **pr-review** | `/initial-setup` | | X | Setup wizard for pr-review (shares Gitea MCP with projman) |
| **pr-review** | `/project-init` | | X | Quick project setup for PR reviews |
| **pr-review** | `/project-sync` | | X | Sync config with git remote after repo move/rename |
| **pr-review** | *SessionStart hook* | X | | Detects git remote vs .env mismatch |
| **pr-review** | `/pr-review` | | X | Full multi-agent PR review with confidence scoring |
| **pr-review** | `/pr-summary` | | X | Quick summary of PR changes |
| **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity |
@@ -41,6 +48,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
| **claude-config-maintainer** | `/config-analyze` | | X | Analyze CLAUDE.md for optimization opportunities |
| **claude-config-maintainer** | `/config-optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
| **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project |
| **cmdb-assistant** | `/initial-setup` | | X | Setup wizard for NetBox MCP server |
| **cmdb-assistant** | `/cmdb-search` | | X | Search NetBox for devices, IPs, sites |
| **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
| **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes |
@@ -53,6 +61,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
| Category | Plugins | Primary Use |
|----------|---------|-------------|
| **Setup** | projman, pr-review, cmdb-assistant | `/initial-setup`, `/project-init` |
| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
@@ -66,6 +75,8 @@ Quick reference for all commands in the Leo Claude Marketplace.
| Plugin | Hook Event | Behavior |
|--------|------------|----------|
| **projman** | SessionStart | Checks git remote vs .env; warns if mismatch detected |
| **pr-review** | SessionStart | Checks git remote vs .env; warns if mismatch detected |
| **doc-guardian** | PostToolUse (Write/Edit) | Silently tracks documentation drift |
| **doc-guardian** | Stop | Prompts to sync if drift detected |
| **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities |
@@ -151,17 +162,32 @@ Managing infrastructure with CMDB:
4. /cmdb-site view Y # Check site info
```
### Example 7: New Project Setup
### Example 7: First-Time Setup (New Machine)
Setting up a project with marketplace plugins:
Setting up the marketplace for the first time:
```
1. /config-init # Create CLAUDE.md
2. /initial-setup # Setup projman (if using)
1. /initial-setup # Full setup: MCP + system config + project
# → Follow prompts for Gitea URL, org
# → Add token manually when prompted
# → Confirm repository name
2. # Restart Claude Code session
3. /labels-sync # Sync Gitea labels
4. /sprint-plan # Plan first sprint
```
### Example 8: New Project Setup (System Already Configured)
Adding a new project when system config exists:
```
1. /project-init # Quick project setup
# → Confirms detected repo name
# → Creates .env
2. /labels-sync # Sync Gitea labels
3. /sprint-plan # Plan first sprint
```
---
## Quick Tips
@@ -188,4 +214,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env` or `~/.config/
---
*Last Updated: 2026-01-20*
*Last Updated: 2026-01-21*

591
docs/CONFIGURATION.md
View File

@@ -2,92 +2,331 @@
Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.
## Overview
---
## Quick Start
**After installing the marketplace and plugins via Claude Code:**
```
/initial-setup
```
The interactive wizard handles everything except manually adding your API tokens.
---
## Setup Flow Diagram
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ FIRST TIME SETUP │
│ (once per machine) │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
/initial-setup
│
┌──────────────────────────────┼──────────────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PHASE 1 │ │ PHASE 2 │ │ PHASE 3 │
│ Automated │───────────▶│ Automated │───────────▶│ Interactive │
│ │ │ │ │ │
│ • Check │ │ • Find MCP path │ │ • Ask Gitea URL │
│ Python │ │ • Create venv │ │ • Ask Org name │
│ version │ │ • Install deps │ │ • Create config │
└─────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌───────────────────────────┐
│ PHASE 4 │
│ USER ACTION │
│ │
│ Edit config file to add │
│ API token (for security) │
│ │
│ nano ~/.config/claude/ │
│ gitea.env │
└───────────────────────────┘
│
▼
┌──────────────────────────────┬──────────────────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ PHASE 5 │ │ PHASE 6 │ │ PHASE 7 │
│ Interactive │ │ Automated │ │ Automated │
│ │ │ │ │ │
│ • Confirm │ │ • Create .env │ │ • Test API │
│ repo name │ │ • Check │ │ • Show summary │
│ from git │ │ .gitignore │ │ • Restart note │
└─────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌───────────────────────────┐
│ RESTART SESSION │
│ │
│ MCP tools available │
│ after restart │
└───────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ NEW PROJECT SETUP │
│ (once per project) │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
/project-init /initial-setup
(direct path) (smart detection)
│ │
│ ┌──────────┴──────────┐
│ ▼ ▼
│ "Quick setup" "Full setup"
│ (skips to (re-runs
│ project config) everything)
│ │ │
└────────────────────┴─────────────────────┘
│
▼
┌─────────────────────┐
│ PROJECT CONFIG │
│ │
│ • Detect repo from │
│ git remote │
│ • Confirm with user │
│ • Create .env │
│ • Check .gitignore │
└─────────────────────┘
│
▼
Done!
```
---
## What Runs Automatically vs User Interaction
### `/initial-setup` - Full Setup
| Phase | Type | What Happens |
|-------|------|--------------|
| **1. Environment Check** | Automated | Verifies Python 3.10+ is installed |
| **2. MCP Server Setup** | Automated | Finds plugin path, creates venv, installs dependencies |
| **3. System Config Creation** | Interactive | Asks for Gitea URL and organization name |
| **4. Token Entry** | **User Action** | User manually edits config file to add API token |
| **5. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
| **7. Validation** | Automated | Tests API connectivity, shows summary |
### `/project-init` - Quick Project Setup
| Phase | Type | What Happens |
|-------|------|--------------|
| **1. Pre-flight Check** | Automated | Verifies system config exists |
| **2. Project Detection** | Interactive | Shows detected repo name, asks for confirmation |
| **3. Project Config** | Automated | Creates/updates `.env` file |
| **4. Gitignore Check** | Interactive | Asks to add `.env` to `.gitignore` if missing |
---
## Three Commands for Different Scenarios
| Command | When to Use | What It Does |
|---------|-------------|--------------|
| `/initial-setup` | First time on a machine | Full setup: MCP server + system config + project config |
| `/project-init` | Starting a new project | Quick setup: project config only (assumes system is ready) |
| `/project-sync` | After repo move/rename | Updates .env to match current git remote |
**Typical workflow:**
1. Install plugin → run `/initial-setup` (once per machine)
2. Start new project → run `/project-init` (once per project)
3. Repository moved? → run `/project-sync` (updates config)
**Smart features:**
- `/initial-setup` detects existing system config and offers quick project setup
- All commands validate org/repo via Gitea API before saving (auto-fills if verified)
- SessionStart hook automatically detects git remote vs .env mismatches
---
## Configuration Architecture
This marketplace uses a **hybrid configuration** approach:
- **System-level:** Credentials and service configuration (stored once per machine)
- **Project-level:** Repository-specific settings (stored per project)
```
┌─────────────────────────────────────────────────────────────────┐
│ SYSTEM-LEVEL (once per machine) │
│ ~/.config/claude/ │
├─────────────────────────────────────────────────────────────────┤
│ gitea.env │ GITEA_URL, GITEA_TOKEN │
│ netbox.env │ NETBOX_URL, NETBOX_TOKEN │
│ git-flow.env │ GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc. │
└─────────────────────────────────────────────────────────────────┘
│
│ Shared across all projects
▼
┌─────────────────────────────────────────────────────────────────┐
│ PROJECT-LEVEL (once per project) │
│ <project-root>/.env │
├─────────────────────────────────────────────────────────────────┤
│ GITEA_ORG │ Organization for this project │
│ GITEA_REPO │ Repository name for this project │
│ GIT_WORKFLOW_STYLE │ (optional) Override system default │
│ PR_REVIEW_* │ (optional) PR review settings │
└─────────────────────────────────────────────────────────────────┘
```
**Benefits:**
- 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)
- Easy multi-project setup (just run `/project-init` in each project)
- Security (tokens never committed to git, never typed into AI chat)
- Project isolation (each project can override defaults)
---
## Prerequisites
Before configuring any plugin:
Before running `/initial-setup`:
1. **Python 3.10+** installed
```bash
python3 --version # Should be 3.10.0 or higher
```
2. **Git repository** initialized
2. **Git repository** initialized (for project setup)
```bash
git status # Should show initialized repository
```
3. **Claude Code** installed and working
3. **Claude Code** installed and working with the marketplace
---
## System-Level Configuration
## Setup Methods
Configuration files stored in `~/.config/claude/`:
### Method 1: Interactive Wizard (Recommended)
Run the setup wizard in Claude Code:
```
/initial-setup
```
The wizard will guide you through each step interactively.
**Note:** After first-time setup, you'll need to restart your Claude Code session for MCP tools to become available.
### Method 2: Manual Setup
If you prefer to set up manually or need to troubleshoot:
#### Step 1: MCP Server Setup
```bash
# Navigate to marketplace directory
cd /path/to/leo-claude-mktplace
# Set up Gitea MCP server
cd mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
# (Optional) Set up NetBox MCP server
cd ../netbox
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
```
#### Step 2: System Configuration
```bash
mkdir -p ~/.config/claude
```
### Gitea Configuration
Required by: `projman`, `pr-review`
```bash
# Gitea configuration (credentials only)
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
GITEA_TOKEN=your_token_here
EOF
# Secure the file
chmod 600 ~/.config/claude/gitea.env
```
**Variables:**
#### Step 3: Project Configuration
In each project root:
```bash
cat > .env << 'EOF'
GITEA_ORG=your-organization
GITEA_REPO=your-repo-name
EOF
```
Add `.env` to `.gitignore` if not already there.
### Method 3: Automation Script (CI/Scripting)
For automated setups or CI environments:
```bash
cd /path/to/leo-claude-mktplace
./scripts/setup.sh
```
This script is useful for CI/CD pipelines and bulk provisioning.
---
## Configuration Reference
### System-Level Files
Located in `~/.config/claude/`:
| File | Required By | Purpose |
|------|-------------|---------|
| `gitea.env` | projman, pr-review | Gitea API credentials |
| `netbox.env` | cmdb-assistant | NetBox API credentials |
| `git-flow.env` | git-flow | Default git workflow settings |
### Gitea Configuration
```bash
# ~/.config/claude/gitea.env
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_token_here
```
| Variable | Description | Example |
|----------|-------------|---------|
| `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` |
| `GITEA_TOKEN` | Personal access token | `glpat-xxx...` |
| `GITEA_ORG` | Organization name | `bandit` |
| `GITEA_TOKEN` | Personal access token | `abc123...` |
**Generating Gitea Token:**
**Note:** `GITEA_ORG` is configured at the project level (see below) since different projects may belong to different organizations.
**Generating a Gitea Token:**
1. Log into Gitea → **User Icon** → **Settings**
2. **Applications** tab → **Manage Access Tokens**
3. **Generate New Token** with permissions:
- `repo` (all sub-permissions)
- `read:org`
- `read:user`
- `write:repo` (for wiki)
- `write:repo` (for wiki access)
4. Copy token immediately (shown only once)
### NetBox Configuration
Required by: `cmdb-assistant`
```bash
cat > ~/.config/claude/netbox.env << 'EOF'
# NetBox API Configuration
# ~/.config/claude/netbox.env
NETBOX_URL=https://netbox.example.com
NETBOX_TOKEN=your_netbox_token_here
EOF
chmod 600 ~/.config/claude/netbox.env
```
**Variables:**
| Variable | Description | Example |
|----------|-------------|---------|
| `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` |
@@ -95,11 +334,8 @@ chmod 600 ~/.config/claude/netbox.env
### Git-Flow Configuration
Optional system defaults for: `git-flow`
```bash
cat > ~/.config/claude/git-flow.env << 'EOF'
# Git-Flow Default Configuration
# ~/.config/claude/git-flow.env
GIT_WORKFLOW_STYLE=feature-branch
GIT_DEFAULT_BASE=development
GIT_AUTO_DELETE_MERGED=true
@@ -107,170 +343,110 @@ GIT_AUTO_PUSH=false
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
GIT_COMMIT_STYLE=conventional
GIT_CO_AUTHOR=true
EOF
```
| Variable | Default | Description |
|----------|---------|-------------|
| `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy |
| `GIT_DEFAULT_BASE` | `development` | Default base branch |
| `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches |
| `GIT_AUTO_PUSH` | `false` | Auto-push after commit |
| `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches |
| `GIT_COMMIT_STYLE` | `conventional` | Commit message style |
| `GIT_CO_AUTHOR` | `true` | Include Claude co-author |
---
## Project-Level Configuration
Create `.env` in each project root:
### Gitea Repository (projman, pr-review)
```bash
# .env in project root
# Required for projman, pr-review
GITEA_ORG=your-organization
GITEA_REPO=your-repo-name
```
### Git-Flow (project overrides)
```bash
# .env in project root
# Optional: Override git-flow defaults
GIT_WORKFLOW_STYLE=pr-required
GIT_DEFAULT_BASE=main
```
### PR Review
```bash
# .env in project root
# Optional: PR review settings
PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
PR_REVIEW_AUTO_SUBMIT=false
```
---
## MCP Server Installation
MCP servers are located at repository root: `mcp-servers/`
### Gitea MCP Server
```bash
cd mcp-servers/gitea
# Create virtual environment
python3 -m venv .venv
# Activate
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Verify
python -c "from mcp_server import server; print('OK')"
deactivate
```
### NetBox MCP Server
```bash
cd mcp-servers/netbox
# Create virtual environment
python3 -m venv .venv
# Activate
source .venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Verify
python -c "from mcp_server import server; print('OK')"
deactivate
```
| Variable | Required | Description |
|----------|----------|-------------|
| `GITEA_ORG` | Yes | Gitea organization for this project |
| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
| `GIT_WORKFLOW_STYLE` | No | Override system default |
| `PR_REVIEW_*` | No | PR review settings |
---
## Plugin Configuration Reference
## Plugin Configuration Summary
### projman
| Level | Variable | Default | Description |
|-------|----------|---------|-------------|
| System | `GITEA_URL` | (required) | Gitea API base URL |
| System | `GITEA_TOKEN` | (required) | API token |
| System | `GITEA_ORG` | (required) | Organization name |
| Project | `GITEA_REPO` | (required) | Repository name |
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen`
### pr-review
| Level | Variable | Default | Description |
|-------|----------|---------|-------------|
| System | `GITEA_URL` | (required) | Gitea API base URL |
| System | `GITEA_TOKEN` | (required) | API token |
| Project | `GITEA_REPO` | (required) | Repository name |
| Project | `PR_REVIEW_CONFIDENCE_THRESHOLD` | `0.5` | Minimum confidence |
| Project | `PR_REVIEW_AUTO_SUBMIT` | `false` | Auto-submit reviews |
**Commands:** `/pr-review`, `/pr-summary`, `/pr-findings`
### git-flow
| Level | Variable | Default | Description |
|-------|----------|---------|-------------|
| System/Project | `GIT_WORKFLOW_STYLE` | `feature-branch` | Branching strategy |
| System/Project | `GIT_DEFAULT_BASE` | `development` | Default base branch |
| System/Project | `GIT_AUTO_DELETE_MERGED` | `true` | Delete merged branches |
| System/Project | `GIT_AUTO_PUSH` | `false` | Auto-push after commit |
| System/Project | `GIT_PROTECTED_BRANCHES` | `main,master,...` | Protected branches |
| System/Project | `GIT_COMMIT_STYLE` | `conventional` | Commit message style |
| System/Project | `GIT_CO_AUTHOR` | `true` | Include Claude co-author |
**Commands:** `/commit`, `/commit-push`, `/commit-merge`, `/commit-sync`, `/branch-start`, `/branch-cleanup`, `/git-status`, `/git-config`
### clarity-assist
No configuration required. Uses sensible defaults.
**Commands:** `/clarify`, `/quick-clarify`
### cmdb-assistant
| Level | Variable | Default | Description |
|-------|----------|---------|-------------|
| System | `NETBOX_URL` | (required) | NetBox API base URL |
| System | `NETBOX_TOKEN` | (required) | API token |
### doc-guardian
No configuration required. Hook-based plugin.
### code-sentinel
No configuration required. Hook-based plugin.
### project-hygiene
No configuration required. Hook-based plugin.
### claude-config-maintainer
No configuration required.
| Plugin | System Config | Project Config | Setup Commands |
|--------|---------------|----------------|----------------|
| **projman** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
| **pr-review** | gitea.env | .env (GITEA_ORG, GITEA_REPO) | `/initial-setup`, `/project-init`, `/project-sync` |
| **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
| **clarity-assist** | None | None | None needed |
| **cmdb-assistant** | netbox.env | None | `/initial-setup` |
| **doc-guardian** | None | None | None needed |
| **code-sentinel** | None | None | None needed |
| **project-hygiene** | None | None | None needed |
| **claude-config-maintainer** | None | None | None needed |
---
## Multi-Project Setup
## Multi-Project Workflow
1. **System config:** Set up once (credentials)
2. **Project config:** Create `.env` in each project root
Once system-level config is set up, adding new projects is simple:
**Example:**
```bash
# ~/projects/my-app/.env
GITEA_REPO=my-app
# ~/projects/another-app/.env
GITEA_REPO=another-app
GIT_WORKFLOW_STYLE=trunk-based
**Option 1: Use `/project-init` (faster)**
```
cd ~/projects/new-project
/project-init
```
**Option 2: Use `/initial-setup` (auto-detects)**
```
cd ~/projects/new-project
/initial-setup
# → Detects system config exists
# → Offers "Quick project setup" option
```
Both approaches work. Use `/project-init` when you know the system is already configured.
---
## Automatic Validation Features
### API Validation
When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
1. **Detect** organization and repository from git remote URL
2. **Validate** via Gitea API: `GET /api/v1/repos/{org}/{repo}`
3. **Auto-fill** if repository exists and is accessible (no confirmation needed)
4. **Ask for confirmation** only if validation fails (404 or permission error)
This catches typos and permission issues before saving configuration.
### Mismatch Detection (SessionStart Hook)
When you start a Claude Code session, a hook automatically:
1. Reads `GITEA_ORG` and `GITEA_REPO` from `.env`
2. Compares with current `git remote get-url origin`
3. **Warns** if mismatch detected: "Repository location mismatch. Run `/project-sync` to update."
This helps when you:
- Move a repository to a different organization
- Rename a repository
- Clone a repo but forget to update `.env`
---
@@ -279,31 +455,29 @@ GIT_WORKFLOW_STYLE=trunk-based
### Test Gitea Connection
```bash
curl -H "Authorization: token YOUR_TOKEN" \
https://gitea.example.com/api/v1/user
source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
```
### Test MCP Server
### Verify Project Setup
```bash
cd mcp-servers/gitea
source .venv/bin/activate
python -c "from mcp_server import server; print('OK')"
In Claude Code, after restarting your session:
```
### Run Plugin Setup
```bash
# For projman
/initial-setup
/labels-sync
```
If this works, your setup is complete.
---
## Troubleshooting
### Configuration not found
### MCP tools not available
**Cause:** Session wasn't restarted after setup.
**Solution:** Exit Claude Code and start a new session.
### "Configuration not found" error
```bash
# Check system config exists
@@ -317,23 +491,25 @@ stat ~/.config/claude/gitea.env
```bash
# Test token directly
curl -H "Authorization: token YOUR_TOKEN" \
https://gitea.example.com/api/v1/user
# Regenerate if invalid
source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
```
### MCP server not starting
If you get 401, regenerate your token in Gitea.
### MCP server won't start
```bash
# Check venv exists
ls mcp-servers/gitea/.venv
ls /path/to/mcp-servers/gitea/.venv
# Reinstall if missing
cd mcp-servers/gitea
cd /path/to/mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate
```
### Wrong repository
@@ -342,7 +518,7 @@ pip install -r requirements.txt
# Check project .env
cat .env
# Verify GITEA_REPO matches exactly
# Verify GITEA_REPO matches the Gitea repository name exactly
```
---
@@ -358,23 +534,14 @@ cat .env
chmod 600 ~/.config/claude/*.env
```
3. **Rotate tokens periodically**
3. **Never type tokens into AI chat**
- Always edit config files directly in your editor
- The `/initial-setup` wizard respects this
4. **Rotate tokens periodically**
- Every 6-12 months
- Immediately if compromised
4. **Minimum permissions**
5. **Minimum permissions**
- Only grant required token permissions
- Use separate tokens for different environments
---
## Quick Setup Checklist
- [ ] Python 3.10+ installed
- [ ] `~/.config/claude/` directory created
- [ ] Service credentials configured (gitea.env, netbox.env)
- [ ] Configuration files secured (chmod 600)
- [ ] MCP servers installed with venv
- [ ] Project `.env` created with repository settings
- [ ] Connections tested
- [ ] Plugin commands verified

118
docs/UPDATING.md
View File

@@ -2,6 +2,8 @@
This guide covers how to update your local installation when new versions are released.
---
## Quick Update
```bash
@@ -13,12 +15,40 @@ git pull origin main
./scripts/post-update.sh
```
**Then restart your Claude Code session** to load any changes.
---
## What the Post-Update Script Does
1. **Updates Python dependencies** for MCP servers
1. **Updates Python dependencies** for MCP servers (gitea, netbox)
2. **Shows recent changelog entries** so you know what changed
3. **Validates your configuration** is still compatible
---
## After Updating: Re-run Setup if Needed
### When to Re-run `/initial-setup`
You typically **don't need** to re-run setup after updates. However, re-run if:
- Changelog mentions **new required environment variables**
- Changelog mentions **breaking changes** to configuration
- MCP tools stop working after update
### For Existing Projects
If an update requires new project-level configuration:
```
/project-init
```
This will detect existing settings and only add what's missing.
---
## Manual Steps After Update
Some updates may require manual configuration changes:
@@ -29,7 +59,7 @@ If the changelog mentions new environment variables:
1. Check the variable name and purpose in the changelog
2. Add it to the appropriate config file:
- Gitea variables → `~/.config/claude/gitea.env`
- System variables → `~/.config/claude/gitea.env` or `netbox.env`
- Project variables → `.env` in your project root
### New MCP Server Features
@@ -37,20 +67,56 @@ If the changelog mentions new environment variables:
If a new MCP server tool is added:
1. The post-update script handles dependency installation
2. Check `plugins/projman/README.md` for usage documentation
3. New tools are available immediately after update
2. Check plugin documentation for usage
3. New tools are available immediately after session restart
### Breaking Changes
Breaking changes will be clearly marked in CHANGELOG.md with migration instructions.
## Troubleshooting
### Setup Script and Configuration Workflow Changes
When updating, review if changes affect the setup workflow:
1. **Check for setup command changes:**
```bash
git diff HEAD~1 plugins/*/commands/initial-setup.md
git diff HEAD~1 plugins/*/commands/project-init.md
git diff HEAD~1 plugins/*/commands/project-sync.md
```
2. **Check for hook changes:**
```bash
git diff HEAD~1 plugins/*/hooks/hooks.json
```
3. **Check for configuration structure changes:**
```bash
git diff HEAD~1 docs/CONFIGURATION.md
```
**If setup commands changed:**
- Review what's new (new validation steps, new prompts, etc.)
- Consider re-running `/initial-setup` or `/project-init` to benefit from improvements
- Existing configurations remain valid unless changelog notes breaking changes
**If hooks changed:**
- Restart your Claude Code session to load new hooks
- New hooks (like SessionStart validation) activate automatically
**If configuration structure changed:**
- Check if new variables are required
- Run `/project-sync` if repository detection logic improved
---
## Troubleshooting Updates
### Dependencies fail to install
```bash
# Rebuild virtual environment
cd plugins/projman/mcp-servers/gitea
cd mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
@@ -61,14 +127,23 @@ deactivate
### Configuration no longer works
1. Check CHANGELOG.md for breaking changes
2. Compare your config files with updated `.env.example` (if provided)
3. Run `./scripts/setup.sh` to validate configuration
2. Run `/initial-setup` to re-validate and fix configuration
3. Compare your config files with documentation in `docs/CONFIGURATION.md`
### MCP server won't start
### MCP server won't start after update
1. Check Python version: `python3 --version` (requires 3.10+)
2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv`
3. Check logs for specific errors
2. Verify venv exists: `ls mcp-servers/gitea/.venv`
3. Restart Claude Code session
4. Check logs for specific errors
### New commands not available
1. Restart your Claude Code session
2. Verify the plugin is still installed
3. Check if the command requires additional setup
---
## Version Pinning
@@ -79,15 +154,28 @@ To stay on a specific version:
git tag
# Checkout specific version
git checkout v2.2.0
git checkout v3.0.0
# Run post-update
./scripts/post-update.sh
```
---
## Checking Current Version
The version is displayed in the main README.md title and in `CHANGELOG.md`.
```bash
# Check version from changelog
head -20 CHANGELOG.md
```
---
## Getting Help
- Check `plugins/projman/README.md` for projman documentation
- Check `plugins/projman/CONFIGURATION.md` for setup guide
- Review CHANGELOG.md for recent changes
- Check `docs/CONFIGURATION.md` for setup guide
- Check `docs/COMMANDS-CHEATSHEET.md` for command reference
- Review `CHANGELOG.md` for recent changes
- Search existing issues in Gitea

160
plugins/cmdb-assistant/commands/initial-setup.md Normal file
View File

@@ -0,0 +1,160 @@
---
description: Interactive setup wizard for cmdb-assistant plugin - configures NetBox MCP server
---
# CMDB Assistant Setup Wizard
This command sets up the cmdb-assistant plugin with NetBox integration.
## Important Context
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
- **MCP tools won't work until after setup + session restart**
- **Uses NetBox MCP server (separate from Gitea MCP)**
---
## Phase 1: Environment Validation
### Step 1.1: Check Python Version
```bash
python3 --version
```
If below 3.10, stop setup and inform user.
---
## Phase 2: MCP Server Setup
### Step 2.1: Locate NetBox MCP Server
```bash
find ~/.claude ~/.config/claude -name "mcp_server" -path "*netbox*" 2>/dev/null | head -5
```
If not found, ask user for marketplace location.
### Step 2.2: Check Virtual Environment
```bash
ls -la /path/to/mcp-servers/netbox/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
```
### Step 2.3: Create Virtual Environment (if missing)
```bash
cd /path/to/mcp-servers/netbox && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
---
## Phase 3: System Configuration
### Step 3.1: Create Config Directory
```bash
mkdir -p ~/.config/claude
```
### Step 3.2: Check NetBox Configuration
```bash
cat ~/.config/claude/netbox.env 2>/dev/null || echo "FILE_NOT_FOUND"
```
**If file exists with valid values:** Skip to Phase 4.
**If missing or has placeholders:** Continue.
### Step 3.3: Gather NetBox Information
Use AskUserQuestion:
- Question: "What is your NetBox server URL? (e.g., https://netbox.company.com)"
- Header: "NetBox URL"
- Options:
- "Other (I'll provide the URL)"
Ask user to provide the URL.
### Step 3.4: Create Configuration File
```bash
cat > ~/.config/claude/netbox.env << 'EOF'
# NetBox API Configuration
# Generated by cmdb-assistant /initial-setup
NETBOX_URL=<USER_PROVIDED_URL>
NETBOX_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/netbox.env
```
### Step 3.5: Token Instructions
---
**Action Required: Add Your NetBox API Token**
I've created `~/.config/claude/netbox.env` but you need to add your API token manually.
**Steps:**
1. Open: `nano ~/.config/claude/netbox.env`
2. Generate token in NetBox: Admin → API Tokens → Add Token
3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
4. Save the file
---
Use AskUserQuestion:
- Question: "Have you added your NetBox token?"
- Header: "Token"
- Options:
- "Yes, I've added the token"
- "Skip for now"
---
## Phase 4: Validation
### Step 4.1: Test Configuration (if token was added)
```bash
source ~/.config/claude/netbox.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Token $NETBOX_TOKEN" "$NETBOX_URL/api/"
```
Report result:
- 200: Success
- 403: Invalid token
- Other: Connection issue
### Step 4.2: Summary
```
╔════════════════════════════════════════════════════════════╗
║ CMDB-ASSISTANT SETUP COMPLETE ║
╠════════════════════════════════════════════════════════════╣
║ MCP Server (NetBox): ✓ Ready ║
║ System Config: ✓ ~/.config/claude/netbox.env ║
╚════════════════════════════════════════════════════════════╝
```
### Step 4.3: Session Restart Notice
---
**⚠️ Session Restart Required**
Restart your Claude Code session for MCP tools to become available.
**After restart, you can:**
- Run `/cmdb-device <hostname>` to look up a device
- Run `/cmdb-ip <address>` to look up an IP address
- Run `/cmdb-site <name>` to look up a site
- Run `/cmdb-search <query>` for general search
---
## Note on Project Configuration
cmdb-assistant does not require project-level configuration. The NetBox connection is system-wide and not tied to specific repositories.

273
plugins/pr-review/commands/initial-setup.md Normal file
View File

@@ -0,0 +1,273 @@
---
description: Interactive setup wizard for pr-review plugin - configures Gitea MCP and project settings
---
# PR Review Setup Wizard
This command sets up the pr-review plugin. It shares the Gitea MCP server with projman, so if you've already run `/initial-setup` for projman, most of the work is done.
## Important Context
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
- **MCP tools won't work until after setup + session restart**
- **Shares Gitea MCP server with projman plugin**
---
## Phase 1: Check Existing Setup
### Step 1.1: Check if Gitea MCP is Already Configured
First, check if the system configuration already exists (from projman or previous setup):
```bash
cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
```
**If file exists with valid values (no placeholders):**
- Skip to Phase 3 (Project Configuration)
- Inform user: "Gitea configuration found. Skipping system setup."
**If file doesn't exist or has placeholders:**
- Continue to Phase 2
### Step 1.2: Check if projman is Installed
Check if projman plugin exists (they share MCP server):
```bash
find ~/.claude ~/.config/claude -name "projman" -type d 2>/dev/null | head -1
```
**If projman exists:**
- Suggest: "The projman plugin is installed and shares the same Gitea MCP server. Consider running `/initial-setup` from projman for the full setup wizard."
Use AskUserQuestion:
- Question: "How would you like to proceed with setup?"
- Header: "Setup"
- Options:
- "Continue with pr-review setup (Recommended if not using projman)"
- "I'll use projman's /initial-setup instead"
**If user chooses projman setup:** End here with instructions to run projman's setup.
---
## Phase 2: System Setup (if needed)
This is a condensed version focusing on what pr-review needs.
### Step 2.1: Python and MCP Server
Check Python version:
```bash
python3 --version
```
If below 3.10, stop and inform user.
Locate and set up the MCP server:
```bash
find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5
```
If venv doesn't exist, create it:
```bash
cd /path/to/mcp-servers/gitea && python3 -m venv .venv && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
### Step 2.2: Gitea Configuration
Create config directory:
```bash
mkdir -p ~/.config/claude
```
Use AskUserQuestion:
- Question: "What is your Gitea server URL?"
- Header: "Gitea URL"
- Options:
- "https://gitea.hotserv.cloud"
- "Other (I'll provide the URL)"
Create configuration file (credentials only, org is per-project):
```bash
cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration
# Generated by pr-review /initial-setup
# Note: GITEA_ORG is configured per-project in .env
GITEA_URL=<USER_PROVIDED_URL>
GITEA_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/gitea.env
```
### Step 2.3: Token Instructions
Display these instructions:
---
**Action Required: Add Your Gitea API Token**
I've created `~/.config/claude/gitea.env` but you need to add your API token manually.
**Steps:**
1. Open: `nano ~/.config/claude/gitea.env`
2. Generate token in Gitea: Settings → Applications → Generate New Token
- Permissions needed: `repo`, `read:org`, `read:user`
3. Replace `PASTE_YOUR_TOKEN_HERE` with your token
4. Save the file
---
Use AskUserQuestion:
- Question: "Have you added your Gitea token?"
- Header: "Token"
- Options:
- "Yes, I've added the token"
- "Skip for now"
---
## Phase 3: Project Configuration
### Step 3.1: Check Current Directory
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
### Step 3.2: Check Existing Project Config
```bash
cat .env 2>/dev/null | grep GITEA_REPO || echo "NOT_FOUND"
```
If `GITEA_REPO` is already set, skip to Phase 4.
### Step 3.3: Detect Organization and Repository
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 3.4: Validate Repository via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 3.7 |
| **404** | Not found - proceed to Step 3.5 |
| **401/403** | Permission issue - warn, proceed to Step 3.5 |
### Step 3.5: Confirm Organization (only if validation failed)
Use AskUserQuestion:
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify"
### Step 3.6: Confirm Repository (only if validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct repository?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify"
**After corrections, re-validate via API (Step 3.4).**
### Step 3.7: Create/Update Project Config
If `.env` exists, append:
```bash
echo "GITEA_ORG=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
If `.env` doesn't exist:
```bash
cat > .env << 'EOF'
# Project Configuration
GITEA_ORG=<ORG_NAME>
GITEA_REPO=<REPO_NAME>
EOF
```
### Step 3.5: PR Review Settings (Optional)
Use AskUserQuestion:
- Question: "Do you want to configure PR review settings?"
- Header: "Settings"
- Options:
- "Use defaults (Recommended)"
- "Let me customize"
If customize, ask about:
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
---
## Phase 4: Validation and Next Steps
### Step 4.1: Test Configuration (if token was added)
```bash
source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
```
Report result:
- 200: Success
- 401: Invalid token
- Other: Connection issue
### Step 4.2: Summary
```
╔════════════════════════════════════════════════════════════╗
║ PR-REVIEW SETUP COMPLETE ║
╠════════════════════════════════════════════════════════════╣
║ MCP Server (Gitea): ✓ Ready ║
║ System Config: ✓ ~/.config/claude/gitea.env ║
║ Project Config: ✓ ./.env ║
╚════════════════════════════════════════════════════════════╝
```
### Step 4.3: Session Restart Notice
---
**⚠️ Session Restart Required**
Restart your Claude Code session for MCP tools to become available.
**After restart, you can:**
- Run `/pr-review <PR_NUMBER>` to review a pull request
- Run `/pr-summary <PR_NUMBER>` for a quick summary
- Run `/pr-findings <PR_NUMBER>` to list actionable findings
---
## Available Commands After Setup
| Command | Description |
|---------|-------------|
| `/pr-review <number>` | Full multi-agent PR review with confidence scoring |
| `/pr-summary <number>` | Quick PR summary |
| `/pr-findings <number>` | List findings with severity and line numbers |

136
plugins/pr-review/commands/project-init.md Normal file
View File

@@ -0,0 +1,136 @@
---
description: Quick project setup - configures only project-level settings for PR review
---
# Project Initialization (PR Review)
Fast setup for a new project when system-level configuration is already complete.
**Use this when:**
- You've already run `/initial-setup` on this machine
- You're starting work on a new project/repository
- You just need to configure this project for PR reviews
---
## Pre-Flight Check
### Step 1: Verify System Configuration
```bash
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:**
---
**System configuration not found.**
Please run `/initial-setup` first to configure Gitea credentials.
---
**If SYSTEM_OK:** Continue.
---
## Project Setup
### Step 2: Verify Current Directory
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
### Step 3: Check Existing Configuration
```bash
cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED"
```
If already configured, ask if user wants to keep or reconfigure.
### Step 4: Detect Organization and Repository
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 5: Validate Repository via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - "Verified: <org>/<repo> exists" - skip to Step 8 |
| **404** | Not found - proceed to Step 6 |
| **401/403** | Permission issue - warn, proceed to Step 6 |
### Step 6: Confirm Organization (only if validation failed)
Use AskUserQuestion:
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify"
### Step 7: Confirm Repository (only if validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct repository?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify"
**After corrections, re-validate via API (Step 5).**
### Step 8: Create/Update .env
```bash
echo "GITEA_ORG=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
### Step 9: Optional PR Review Settings
Use AskUserQuestion:
- Question: "Configure PR review settings?"
- Header: "Settings"
- Options:
- "Use defaults (Recommended)"
- "Customize settings"
If customize:
- `PR_REVIEW_CONFIDENCE_THRESHOLD` (default: 0.5)
- `PR_REVIEW_AUTO_SUBMIT` (default: false)
---
## Complete
```
╔══════════════════════════════════════════════════════════════╗
║ PROJECT CONFIGURED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <ORG_NAME> ║
║ Repository: <REPO_NAME> ║
║ Config file: ./.env ║
╚══════════════════════════════════════════════════════════════╝
Ready to review PRs:
• /pr-review <number> - Full multi-agent review
• /pr-summary <number> - Quick summary
• /pr-findings <number> - List findings
```

93
plugins/pr-review/commands/project-sync.md Normal file
View File

@@ -0,0 +1,93 @@
---
description: Sync project configuration with current git remote - use after changing repository location
---
# Project Sync (PR Review)
Updates project configuration when the git remote URL has changed.
**Use this when:**
- Repository was moved to a different organization
- Repository was renamed
- Git remote URL changed
- SessionStart hook detected a mismatch
---
## Step 1: Verify System Configuration
```bash
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:** Run `/initial-setup` first.
---
## Step 2: Read Current .env
```bash
cat .env 2>/dev/null
```
Extract `GITEA_ORG` and `GITEA_REPO` values.
**If missing:** Redirect to `/project-init`.
---
## Step 3: Detect Git Remote
```bash
git remote get-url origin 2>/dev/null
```
Extract organization and repository from URL.
---
## Step 4: Compare Values
| Scenario | Action |
|----------|--------|
| **Match** | "Configuration in sync" - exit |
| **Mismatch** | Show diff, proceed to validation |
---
## Step 5: Validate via Gitea API
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<NEW_ORG>/<NEW_REPO>"
```
| Code | Action |
|------|--------|
| **200** | Verified - proceed to update |
| **404** | Not found - ask to confirm |
| **401/403** | Permission issue - warn |
---
## Step 6: Confirm and Update
Use AskUserQuestion to confirm, then update .env:
```bash
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<NEW_ORG>/' .env
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
```
---
## Step 7: Confirm Success
```
╔══════════════════════════════════════════════════════════════╗
║ CONFIGURATION UPDATED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <NEW_ORG> ║
║ Repository: <NEW_REPO> ║
╚══════════════════════════════════════════════════════════════╝
```

15
plugins/pr-review/hooks/hooks.json Normal file
View File

@@ -0,0 +1,15 @@
{
"hooks": {
"SessionStart": [
{
"matcher": ".*",
"hooks": [
{
"type": "prompt",
"prompt": "Silently check if the project's git remote matches the .env configuration:\n\n1. Read .env to get GITEA_ORG and GITEA_REPO values\n2. Run: git remote get-url origin\n3. Extract org and repo from the remote URL\n4. Compare with .env values\n\nIf mismatch detected:\n- Display a brief warning: 'Repository location mismatch detected. Git remote shows <org>/<repo> but .env has <old-org>/<old-repo>. Run /project-sync to update.'\n\nIf match or no .env exists: Stay silent, do not interrupt.\n\nThis check should be quick and non-blocking."
}
]
}
]
}
}

39
plugins/projman/CONFIGURATION.md
View File

@@ -1,39 +1,10 @@
# Configuration Guide - Projman Plugin
# Configuration - Projman Plugin
For comprehensive configuration instructions, see the **[Centralized Configuration Guide](../../docs/CONFIGURATION.md)**.
See **[docs/CONFIGURATION.md](../../docs/CONFIGURATION.md)** for complete setup instructions.
## Quick Reference
## Quick Commands
### Required Configuration
**System-level** (`~/.config/claude/gitea.env`):
```bash
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_token
GITEA_ORG=your_organization
```
**Project-level** (`.env` in project root):
```bash
GITEA_REPO=your-repo-name
/initial-setup # First time on this machine
/project-init # New project (system already configured)
```
### MCP Server Installation
```bash
cd mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
### Verification
```bash
/initial-setup
/labels-sync
```
---
For detailed setup instructions, troubleshooting, and security best practices, see [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md).

106
plugins/projman/README.md
View File

@@ -25,57 +25,38 @@ Projman transforms a proven 15-sprint workflow into a distributable Claude Code
- Python 3.10+ installed
- Git repository initialized
### 2. Install MCP Server
### 2. Run Interactive Setup
The plugin bundles the Gitea MCP server:
The setup wizard handles everything:
```bash
cd plugins/projman/mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
```
See [CONFIGURATION.md](./CONFIGURATION.md) for detailed setup instructions.
### 3. Configure System-Level Settings
Create system-wide configuration with your Gitea credentials:
```bash
mkdir -p ~/.config/claude
# Gitea configuration
cat > ~/.config/claude/gitea.env << 'EOF'
GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_token_here
GITEA_ORG=your_organization
EOF
# Secure the file
chmod 600 ~/.config/claude/gitea.env
```
### 4. Configure Project-Level Settings
In your project root directory, create a `.env` file:
```bash
# In your project directory
cat > .env << 'EOF'
GITEA_REPO=your-repo-name
EOF
```
### 5. Run Initial Setup
```bash
/initial-setup
```
### 6. Start Planning!
This will:
- Set up the MCP server (Python venv + dependencies)
- Create system config (`~/.config/claude/gitea.env`)
- Guide you through adding your Gitea token
- Detect and validate your repository via API
- Create project config (`.env`)
```bash
**For new projects** (when system is already configured):
```
/project-init
```
**After moving a repository:**
```
/project-sync
```
See [docs/CONFIGURATION.md](../../docs/CONFIGURATION.md) for detailed instructions.
### 3. Start Planning!
```
/sprint-plan
```
@@ -164,15 +145,40 @@ Synchronize label taxonomy from Gitea.
- When new labels are added to Gitea
### `/initial-setup`
Run initial setup for a new project.
Full interactive setup wizard.
**What it does:**
- Validates Gitea MCP server connection
- Tests credential configuration
- Syncs label taxonomy
- Creates required directory structure
- Checks Python version (requires 3.10+)
- Sets up MCP server virtual environment
- Creates system-level config (`~/.config/claude/gitea.env`)
- Guides token setup (manual entry for security)
- Detects and validates repository via Gitea API
- Creates project-level config (`.env` with GITEA_ORG, GITEA_REPO)
**When to use:** First time setting up projman for a project
**When to use:** First time on a new machine
### `/project-init`
Quick project setup (assumes system config exists).
**What it does:**
- Verifies system configuration exists
- Detects organization and repository from git remote
- Validates via Gitea API
- Creates project `.env` file
**When to use:** Starting work on a new project
### `/project-sync`
Sync configuration with current git remote.
**What it does:**
- Compares .env values with git remote URL
- Validates new repository via Gitea API
- Updates .env if mismatch detected
**When to use:** After moving or renaming a repository
**Note:** A SessionStart hook automatically detects mismatches and warns you to run `/project-sync`.
### `/review`
Pre-sprint-close code quality review.

511
plugins/projman/commands/initial-setup.md
View File

@@ -1,114 +1,461 @@
---
description: Run initial setup for projman plugin
description: Interactive setup wizard for projman plugin - configures MCP servers, credentials, and project settings
---
# Initial Setup
# Initial Setup Wizard
Run the installation script to set up the projman plugin.
This command guides the user through complete projman setup interactively. It handles both first-time marketplace setup and per-project configuration.
## What This Does
## Important Context
1. Creates Python virtual environments for MCP servers
2. Installs all dependencies
3. Creates configuration file templates
4. Validates existing configuration
5. Validates repository organization
6. Syncs label taxonomy
7. Reports remaining manual steps
- **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
- **MCP tools won't work until after setup + session restart**
- **Tokens must be entered manually by the user** for security (not typed into chat)
## Execution
---
## Quick Path Detection
**FIRST**, check if system-level setup is already complete:
```bash
cd ${PROJECT_ROOT}
./scripts/setup.sh
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep -v "example.com" | grep "GITEA_TOKEN=" && echo "SYSTEM_CONFIGURED" || echo "SYSTEM_NEEDS_SETUP"
```
## Configuration Structure
**If SYSTEM_CONFIGURED:**
The plugin uses a hybrid configuration approach:
The system-level configuration already exists. Offer the user a choice:
**System-Level (credentials):**
```
~/.config/claude/gitea.env
```
Contains API credentials that work across all projects.
Use AskUserQuestion:
- Question: "System configuration found. What would you like to do?"
- Header: "Setup Mode"
- Options:
- "Quick project setup only (Recommended for new projects)"
- "Full setup (re-check everything)"
**Project-Level (repository/paths):**
```
project-root/.env
```
Contains project-specific settings like repository name.
**If "Quick project setup":**
- Skip directly to **Phase 4: Project-Level Configuration**
- This is equivalent to running `/project-init`
## After Running
**If "Full setup":**
- Continue with Phase 1 below
Review the output for any manual steps required:
**If SYSTEM_NEEDS_SETUP:**
- Continue with Phase 1 (full setup required)
1. **Configure API credentials** in `~/.config/claude/gitea.env`:
```
GITEA_URL=https://gitea.your-company.com
GITEA_TOKEN=your-api-token
GITEA_ORG=your-organization
---
## Phase 1: Environment Validation
### Step 1.1: Check Python Version
Run this command to verify Python 3.10+ is available:
```bash
python3 --version
```
2. **Configure project settings** in `.env`:
```
GITEA_REPO=your-repo-name
WIKIJS_PROJECT=your-project
**If version is below 3.10:**
- Stop setup and inform user: "Python 3.10 or higher is required. Please install it and run /initial-setup again."
- Provide installation hints based on OS (apt, brew, etc.)
**If successful:** Continue to next step.
---
## Phase 2: MCP Server Setup
### Step 2.1: Locate the Plugin Installation
The plugin is installed somewhere on the system. Find the MCP server directory by resolving the path.
First, identify where this plugin is installed. The MCP server should be accessible via the symlink structure. Look for the gitea MCP server:
```bash
# Find the plugin's mcp-servers directory (search common locations)
find ~/.claude ~/.config/claude -name "mcp_server" -path "*gitea*" 2>/dev/null | head -5
```
3. **Run `/labels-sync`** to sync Gitea labels
If found, extract the parent path (the gitea MCP server root).
4. **Verify Gitea Wiki** is accessible and has proper structure
**Alternative:** If the user knows the marketplace location, ask them:
## Pre-Flight Checks
Use AskUserQuestion:
- Question: "Where is the Leo Claude Marketplace installed?"
- Options:
- "~/.claude/plugins/leo-claude-mktplace" (default Claude plugins location)
- "Let me find it automatically"
- Other (user provides path)
The setup script validates:
### Step 2.2: Check if Virtual Environment Exists
- Repository belongs to an organization (required)
- Required label categories exist
- API credentials are valid
- Network connectivity to Gitea
Once you have the MCP server path (e.g., `/path/to/mcp-servers/gitea`), check for the venv:
## Re-Running
This command is safe to run multiple times. It will skip already-completed steps.
## MCP Server Structure
The plugin bundles these MCP servers:
```
plugins/projman/mcp-servers/
└── gitea/
├── .venv/
├── requirements.txt
└── mcp_server/
├── server.py
├── gitea_client.py
└── tools/
├── issues.py
├── labels.py
├── wiki.py
├── milestones.py
└── dependencies.py
```bash
ls -la /path/to/mcp-servers/gitea/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
```
## Troubleshooting
### Step 2.3: Create Virtual Environment (if missing)
**Error: Repository not under organization**
- This plugin requires repositories to belong to a Gitea organization
- Transfer your repository to an organization or create one
If venv doesn't exist:
**Error: Missing required labels**
- Run `/labels-sync` to create missing labels
- Or create them manually in Gitea
```bash
cd /path/to/mcp-servers/gitea && python3 -m venv .venv
```
**Error: Cannot connect to Gitea**
- Verify `GITEA_URL` in `~/.config/claude/gitea.env`
- Check your API token has proper permissions
- Ensure network connectivity
Then install dependencies:
**Error: Virtual environment creation failed**
- Ensure Python 3.8+ is installed
- Check disk space
- Try running `python -m venv .venv` manually in the MCP server directory
```bash
cd /path/to/mcp-servers/gitea && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
**If pip install fails:**
- Show the error to the user
- Suggest: "Check your internet connection and try again. You can also manually run: `cd /path/to/mcp-servers/gitea && source .venv/bin/activate && pip install -r requirements.txt`"
### Step 2.4: NetBox MCP Server (Optional)
Check if the user wants to set up the NetBox MCP server (for cmdb-assistant plugin):
Use AskUserQuestion:
- Question: "Do you want to set up the NetBox MCP server for infrastructure management?"
- Options:
- "Yes, set up NetBox MCP"
- "No, skip NetBox (Recommended if not using cmdb-assistant)"
If yes, repeat steps 2.2-2.3 for `/path/to/mcp-servers/netbox`.
---
## Phase 3: System-Level Configuration
System configuration is stored in `~/.config/claude/` and contains credentials that work across all projects.
### Step 3.1: Create Config Directory
```bash
mkdir -p ~/.config/claude
```
### Step 3.2: Check Gitea Configuration
```bash
cat ~/.config/claude/gitea.env 2>/dev/null || echo "FILE_NOT_FOUND"
```
**If file doesn't exist:** Go to Step 3.3 (Create Template)
**If file exists:** Read it and check if values are placeholders (contain "example.com" or "your_" or "token_here"). If placeholders, go to Step 3.4 (Update Existing).
**If file has real values:** Go to Step 3.5 (Validate).
### Step 3.3: Create Gitea Configuration Template
Gather the Gitea server URL from the user.
Use AskUserQuestion:
- Question: "What is your Gitea server URL? (e.g., https://gitea.company.com)"
- Header: "Gitea URL"
- Options:
- "https://gitea.hotserv.cloud" (if this is Leo's setup)
- "Other (I'll provide the URL)"
If "Other", ask the user to type the URL.
Now create the configuration file with a placeholder for the token:
```bash
cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration
# Generated by /initial-setup
# Note: GITEA_ORG is configured per-project in .env
GITEA_URL=<USER_PROVIDED_URL>
GITEA_TOKEN=PASTE_YOUR_TOKEN_HERE
EOF
chmod 600 ~/.config/claude/gitea.env
```
Replace `<USER_PROVIDED_URL>` with the actual value from the user.
### Step 3.4: Token Entry Instructions
**CRITICAL: Do not ask the user to type the token into chat.**
Display these instructions clearly:
---
**Action Required: Add Your Gitea API Token**
I've created the configuration file at `~/.config/claude/gitea.env` but you need to add your API token manually for security.
**Steps:**
1. Open the file in your editor:
```
nano ~/.config/claude/gitea.env
```
Or use any editor you prefer.
2. Generate a Gitea token (if you don't have one):
- Go to your Gitea instance → User Icon → Settings
- Click "Applications" tab
- Under "Manage Access Tokens", click "Generate New Token"
- Name it something like "claude-code"
- Select permissions: `repo` (all), `read:org`, `read:user`
- Click "Generate Token" and copy it immediately
3. Replace `PASTE_YOUR_TOKEN_HERE` with your actual token
4. Save the file
---
Use AskUserQuestion:
- Question: "Have you added your Gitea token to ~/.config/claude/gitea.env?"
- Header: "Token Added?"
- Options:
- "Yes, I've added the token"
- "I need help generating a token"
- "Skip for now (I'll do it later)"
**If "I need help":** Provide detailed instructions for their specific Gitea instance.
**If "Skip":** Warn that MCP tools won't work until configured, but continue with project setup.
### Step 3.5: Validate Gitea Configuration
Read the config file and verify it has non-placeholder values:
```bash
source ~/.config/claude/gitea.env && echo "URL: $GITEA_URL" && echo "ORG: $GITEA_ORG" && echo "TOKEN_LENGTH: ${#GITEA_TOKEN}"
```
If TOKEN_LENGTH is less than 10 or contains "PASTE" or "your_", the token hasn't been set properly.
**Test connectivity (optional but recommended):**
```bash
source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
```
- **200:** Success! Credentials are valid.
- **401:** Invalid token.
- **404/Connection error:** Invalid URL or network issue.
Report the result to the user.
### Step 3.6: Git-Flow Configuration (Optional)
Use AskUserQuestion:
- Question: "Do you want to configure git-flow defaults for smart commits?"
- Header: "Git-Flow"
- Options:
- "Yes, use recommended defaults (Recommended)"
- "Yes, let me customize"
- "No, skip git-flow configuration"
If yes with defaults:
```bash
cat > ~/.config/claude/git-flow.env << 'EOF'
# Git-Flow Default Configuration
GIT_WORKFLOW_STYLE=feature-branch
GIT_DEFAULT_BASE=development
GIT_AUTO_DELETE_MERGED=true
GIT_AUTO_PUSH=false
GIT_PROTECTED_BRANCHES=main,master,development,staging,production
GIT_COMMIT_STYLE=conventional
GIT_CO_AUTHOR=true
EOF
chmod 600 ~/.config/claude/git-flow.env
```
If customize, use AskUserQuestion for each setting.
---
## Phase 4: Project-Level Configuration
Project configuration is stored in `.env` in the current project root.
### Step 4.1: Verify Current Directory
Confirm we're in the right place:
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
If not a git repo, ask the user:
Use AskUserQuestion:
- Question: "The current directory doesn't appear to be a git repository. Where should I create the project configuration?"
- Options:
- "This directory is correct, continue anyway"
- "Let me navigate to the right directory first"
### Step 4.2: Check Existing Project Configuration
```bash
cat .env 2>/dev/null || echo "FILE_NOT_FOUND"
```
If `.env` exists and has `GITEA_REPO=` set to a non-placeholder value, skip to Phase 5.
### Step 4.3: Infer Organization and Repository from Git Remote
Try to detect org and repo name automatically:
```bash
git remote get-url origin 2>/dev/null
```
Parse the output to extract both organization and repository:
- `git@gitea.example.com:org/repo-name.git` → org: `org`, repo: `repo-name`
- `https://gitea.example.com/org/repo-name.git` → org: `org`, repo: `repo-name`
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 4.4: Validate Repository via Gitea API
**Before asking for confirmation**, verify the repository exists and is accessible:
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
```
**Based on response:**
| HTTP Code | Meaning | Action |
|-----------|---------|--------|
| **200** | Repository exists and accessible | **Auto-fill without asking** - skip to Step 4.7 |
| **404** | Repository not found | Ask user to confirm/correct (Step 4.5) |
| **401/403** | Token issue or no access | Warn about permissions, ask to confirm |
| **Other** | Network/server issue | Warn, ask to confirm manually |
**If 200 OK:** Display confirmation message and skip to Step 4.7:
"Verified: Repository '<detected-org>/<detected-repo>' exists and is accessible."
### Step 4.5: Confirm Organization (only if API validation failed)
Use AskUserQuestion:
- Question: "Repository '<detected-org>/<detected-repo>' was not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify the correct organization"
If no, ask user to provide the correct organization name.
### Step 4.6: Confirm Repository Name (only if API validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct Gitea repository name?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify the correct name"
If no, ask user to provide the correct name.
**After user provides corrections, re-validate via API (Step 4.4)** to ensure the corrected values are valid.
### Step 4.7: Create Project Configuration
```bash
cat > .env << 'EOF'
# Project Configuration for projman
# Generated by /initial-setup
GITEA_ORG=<ORG_NAME>
GITEA_REPO=<REPO_NAME>
EOF
```
Replace `<REPO_NAME>` with the confirmed value.
**Important:** Check if `.env` is in `.gitignore`:
```bash
grep -q "^\.env$" .gitignore 2>/dev/null && echo "GITIGNORE_OK" || echo "GITIGNORE_MISSING"
```
If not in `.gitignore`, warn the user:
"Warning: `.env` is not in your `.gitignore`. Consider adding it to prevent accidentally committing credentials."
---
## Phase 5: Final Validation and Next Steps
### Step 5.1: Summary Report
Display a summary of what was configured:
```
╔══════════════════════════════════════════════════════════════╗
║ SETUP COMPLETE ║
╠══════════════════════════════════════════════════════════════╣
║ MCP Server (Gitea): ✓ Installed ║
║ System Config: ✓ ~/.config/claude/gitea.env ║
║ Project Config: ✓ ./.env ║
║ Gitea Connection: ✓ Verified (or ⚠ Not tested) ║
╚══════════════════════════════════════════════════════════════╝
```
### Step 5.2: Session Restart Notice
**IMPORTANT:** Display this notice clearly:
---
**⚠️ Session Restart Required**
The MCP server has been configured but won't be available until you restart your Claude Code session.
**To complete setup:**
1. Exit this Claude Code session (type `/exit` or close the terminal)
2. Start a new Claude Code session in this project
3. The Gitea MCP tools will now be available
**After restart, you can:**
- Run `/labels-sync` to sync your label taxonomy
- Run `/sprint-plan` to start planning
- Use MCP tools like `list_issues`, `create_issue`, etc.
---
### Step 5.3: Troubleshooting Checklist
If something isn't working after restart, check:
1. **MCP server not found:** Verify venv exists at the expected path
2. **Authentication failed:** Re-check token in `~/.config/claude/gitea.env`
3. **Wrong repository:** Verify `GITEA_REPO` in `./.env` matches Gitea exactly
4. **Network error:** Ensure Gitea URL is accessible from this machine
---
## Re-Running This Command
This command is safe to run multiple times:
- Existing venvs are skipped (not recreated)
- Existing config files are checked for validity
- Only missing or placeholder values are updated
- Project config can be regenerated for new projects
---
## Quick Reference: Files Created
| File | Purpose | Contains |
|------|---------|----------|
| `~/.config/claude/gitea.env` | System credentials | URL, token, org |
| `~/.config/claude/git-flow.env` | Git defaults | Workflow settings |
| `./.env` | Project settings | Repository name |
| `<mcp-server>/.venv/` | Python environment | Dependencies |

218
plugins/projman/commands/project-init.md Normal file
View File

@@ -0,0 +1,218 @@
---
description: Quick project setup - configures only project-level settings (assumes system setup is complete)
---
# Project Initialization
Fast setup for a new project when system-level configuration is already complete.
**Use this when:**
- You've already run `/initial-setup` on this machine
- You're starting work on a new project/repository
- You just need to create the project `.env` file
**Use `/initial-setup` instead if:**
- This is your first time using the plugin
- MCP tools aren't working (might need system setup)
---
## Pre-Flight Check
### Step 1: Verify System Configuration Exists
Quickly verify system setup is complete:
```bash
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:**
Display this message and stop:
---
**System configuration not found or incomplete.**
It looks like the system-level setup hasn't been completed yet. Please run:
```
/initial-setup
```
This will configure both system credentials and this project.
---
**If SYSTEM_OK:** Continue to project setup.
---
## Project Setup
### Step 2: Verify Current Directory
```bash
pwd && git rev-parse --show-toplevel 2>/dev/null || echo "NOT_A_GIT_REPO"
```
If not a git repo, ask:
Use AskUserQuestion:
- Question: "This doesn't appear to be a git repository. Continue anyway?"
- Header: "Directory"
- Options:
- "Yes, continue here"
- "No, I'll navigate to the correct directory"
### Step 3: Check for Existing Configuration
```bash
cat .env 2>/dev/null | grep "GITEA_REPO=" || echo "NOT_CONFIGURED"
```
**If already configured:**
Use AskUserQuestion:
- Question: "This project already has GITEA_ORG and GITEA_REPO configured. What would you like to do?"
- Header: "Existing"
- Options:
- "Keep existing configuration"
- "Reconfigure (replace current settings)"
**If "Keep":** End with success message.
### Step 4: Detect Organization and Repository
Try to auto-detect from git remote:
```bash
git remote get-url origin 2>/dev/null
```
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
### Step 5: Validate Repository via Gitea API
Verify the repository exists and is accessible:
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<detected-org>/<detected-repo>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Auto-fill - display "Verified: <org>/<repo> exists" and skip to Step 8 |
| **404** | Repository not found - proceed to Step 6 |
| **401/403** | Permission issue - warn and proceed to Step 6 |
### Step 6: Confirm Organization (only if API validation failed)
Use AskUserQuestion:
- Question: "Repository not found. Is '<detected-org>' the correct organization?"
- Header: "Organization"
- Options:
- "Yes, that's correct"
- "No, let me specify"
If "No", ask user to type the correct organization name.
### Step 7: Confirm Repository Name (only if API validation failed)
Use AskUserQuestion:
- Question: "Is '<detected-repo-name>' the correct repository name?"
- Header: "Repository"
- Options:
- "Yes, that's correct"
- "No, let me specify"
If "No", ask user to type the correct name.
**After corrections, re-validate via API (Step 5).**
### Step 8: Create/Update Project Configuration
**If `.env` exists:**
Check if it already has other content and append:
```bash
echo "" >> .env
echo "# Added by /project-init" >> .env
echo "GITEA_ORG=<ORG_NAME>" >> .env
echo "GITEA_REPO=<REPO_NAME>" >> .env
```
**If `.env` doesn't exist:**
```bash
cat > .env << 'EOF'
# Project Configuration for projman
# Generated by /project-init
GITEA_ORG=<ORG_NAME>
GITEA_REPO=<REPO_NAME>
EOF
```
### Step 9: Check .gitignore
```bash
grep -q "^\.env$" .gitignore 2>/dev/null && echo "GITIGNORE_OK" || echo "GITIGNORE_MISSING"
```
**If GITIGNORE_MISSING:**
Use AskUserQuestion:
- Question: "`.env` is not in `.gitignore`. Add it to prevent committing secrets?"
- Header: "gitignore"
- Options:
- "Yes, add .env to .gitignore (Recommended)"
- "No, I'll handle it manually"
If yes:
```bash
echo ".env" >> .gitignore
```
---
## Complete
Display success message:
```
╔══════════════════════════════════════════════════════════════╗
║ PROJECT CONFIGURED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <ORG_NAME> ║
║ Repository: <REPO_NAME> ║
║ Config file: ./.env ║
╚══════════════════════════════════════════════════════════════╝
You're ready to use projman commands:
• /sprint-plan - Start sprint planning
• /sprint-status - Check progress
• /labels-sync - Sync label taxonomy
```
---
## Troubleshooting
**MCP tools not working?**
- Run `/initial-setup` for full setup including MCP server
- Restart your Claude Code session after setup
**Wrong repository configured?**
- Edit `.env` directly: `nano .env`
- Or run `/project-init` again and choose "Reconfigure"

196
plugins/projman/commands/project-sync.md Normal file
View File

@@ -0,0 +1,196 @@
---
description: Sync project configuration with current git remote - use after changing repository location or organization
---
# Project Sync
Updates project configuration when the git remote URL has changed (repository moved, renamed, or organization changed).
**Use this when:**
- You moved the repository to a different organization
- You renamed the repository
- You changed the git remote URL
- The SessionStart hook detected a mismatch
---
## Step 1: Verify System Configuration
```bash
cat ~/.config/claude/gitea.env 2>/dev/null | grep -v "^#" | grep -v "PASTE_YOUR" | grep "GITEA_TOKEN=" && echo "SYSTEM_OK" || echo "SYSTEM_MISSING"
```
**If SYSTEM_MISSING:** Stop and instruct user to run `/initial-setup` first.
---
## Step 2: Read Current Configuration
Read the current .env values:
```bash
cat .env 2>/dev/null
```
Extract current values:
- `CURRENT_ORG` from `GITEA_ORG=...`
- `CURRENT_REPO` from `GITEA_REPO=...`
**If .env doesn't exist or has no GITEA values:** Redirect to `/project-init`.
---
## Step 3: Detect Git Remote Values
Get the current git remote:
```bash
git remote get-url origin 2>/dev/null
```
Extract organization:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\/[^/]*$/\1/'
```
Extract repository:
```bash
git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\)\.git$/\1/' | sed 's/.*\/\([^/]*\)$/\1/'
```
---
## Step 4: Compare Values
Compare current .env values with detected git remote values:
| Scenario | Action |
|----------|--------|
| **Both match** | Display "Configuration is in sync" and exit |
| **Organization changed** | Proceed to Step 5 |
| **Repository changed** | Proceed to Step 5 |
| **Both changed** | Proceed to Step 5 |
**If already in sync:**
```
╔══════════════════════════════════════════════════════════════╗
║ CONFIGURATION IN SYNC ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <ORG_NAME> ║
║ Repository: <REPO_NAME> ║
║ Git Remote: matches .env ║
╚══════════════════════════════════════════════════════════════╝
```
Exit here if in sync.
---
## Step 5: Show Detected Changes
Display the detected changes to the user:
```
╔══════════════════════════════════════════════════════════════╗
║ REPOSITORY CHANGE DETECTED ║
╠══════════════════════════════════════════════════════════════╣
║ Current .env │ Git Remote ║
║ Organization: <OLD_ORG> │ <NEW_ORG> ║
║ Repository: <OLD_REPO> │ <NEW_REPO> ║
╚══════════════════════════════════════════════════════════════╝
```
---
## Step 6: Validate New Repository via Gitea API
Verify the new repository exists and is accessible:
```bash
source ~/.config/claude/gitea.env
curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/repos/<NEW_ORG>/<NEW_REPO>"
```
| HTTP Code | Action |
|-----------|--------|
| **200** | Repository verified - proceed to Step 7 |
| **404** | Repository not found - ask user to confirm (Step 6a) |
| **401/403** | Permission issue - warn and ask to confirm |
### Step 6a: Confirm if API Validation Failed
Use AskUserQuestion:
- Question: "The new repository '<NEW_ORG>/<NEW_REPO>' was not found via API. Update configuration anyway?"
- Header: "Not Found"
- Options:
- "Yes, update anyway (I'll fix the remote later)"
- "No, let me fix the git remote first"
- "Let me specify different values"
**If "specify different values":** Ask for correct org and repo, then re-validate.
---
## Step 7: Confirm Update
Use AskUserQuestion:
- Question: "Update project configuration to match git remote?"
- Header: "Confirm"
- Options:
- "Yes, update .env (Recommended)"
- "No, keep current configuration"
**If "No":** Exit without changes.
---
## Step 8: Update Configuration
Update the .env file with new values:
```bash
# Update GITEA_ORG
sed -i 's/^GITEA_ORG=.*/GITEA_ORG=<NEW_ORG>/' .env
# Update GITEA_REPO
sed -i 's/^GITEA_REPO=.*/GITEA_REPO=<NEW_REPO>/' .env
```
Alternatively, if sed doesn't work well, read the file, replace values, and write back.
---
## Step 9: Verify Update
Read the updated .env and display confirmation:
```
╔══════════════════════════════════════════════════════════════╗
║ CONFIGURATION UPDATED ║
╠══════════════════════════════════════════════════════════════╣
║ Organization: <NEW_ORG> ║
║ Repository: <NEW_REPO> ║
║ Status: In sync with git remote ║
╚══════════════════════════════════════════════════════════════╝
Your project configuration has been updated.
MCP tools will now use the new repository.
```
---
## Troubleshooting
**"Repository not found" but it exists:**
- Check your Gitea token has access to the new organization
- Verify the repository name matches exactly (case-sensitive)
- Ensure your token has `repo` permissions
**Git remote URL is wrong:**
- Fix it first: `git remote set-url origin <correct-url>`
- Then run `/project-sync` again
**Want to revert the change:**
- Edit `.env` manually: `nano .env`
- Or run `/project-sync` after fixing the git remote

15
plugins/projman/hooks/hooks.json Normal file
View File

@@ -0,0 +1,15 @@
{
"hooks": {
"SessionStart": [
{
"matcher": ".*",
"hooks": [
{
"type": "prompt",
"prompt": "Silently check if the project's git remote matches the .env configuration:\n\n1. Read .env to get GITEA_ORG and GITEA_REPO values\n2. Run: git remote get-url origin\n3. Extract org and repo from the remote URL\n4. Compare with .env values\n\nIf mismatch detected:\n- Display a brief warning: 'Repository location mismatch detected. Git remote shows <org>/<repo> but .env has <old-org>/<old-repo>. Run /project-sync to update.'\n\nIf match or no .env exists: Stay silent, do not interrupt.\n\nThis check should be quick and non-blocking."
}
]
}
]
}
}

13
scripts/setup.sh
View File

@@ -1,6 +1,17 @@
#!/usr/bin/env bash
#
# setup.sh - Initial setup for Leo Claude Marketplace
# setup.sh - Automated setup for Leo Claude Marketplace
#
# ============================================================================
# NOTE: For interactive setup, use the /initial-setup command in Claude Code
# instead of this script. The command provides a guided wizard experience.
#
# This script is intended for:
# - CI/CD pipelines
# - Automated deployments
# - Bulk machine provisioning
# - Fallback when Claude Code is not available
# ============================================================================
#
# Usage: ./scripts/setup.sh
#