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

feat: add interactive setup wizard with API validation and mismatch detection

Browse Source 
Major improvements to plugin setup experience:

Setup Commands:
- Redesign /initial-setup as interactive wizard (MCP + system + project config)
- Add /project-init for quick project-only setup
- Add /project-sync for handling repository moves/renames
- Add Gitea API validation to auto-fill org/repo when verified

Configuration Changes:
- Move GITEA_ORG from system to project level (supports multi-org users)
- System config now only contains GITEA_URL and GITEA_TOKEN
- Project .env now contains GITEA_ORG and GITEA_REPO

Automation:
- Add SessionStart hook for projman and pr-review
- Automatically detects git remote vs .env mismatch
- Warns user to run /project-sync when mismatch found

Documentation:
- Unify configuration docs (remove duplicate in plugins/projman)
- Add flow diagrams to CONFIGURATION.md
- Add setup script review guidance to UPDATING.md
- Update COMMANDS-CHEATSHEET.md with new commands and hooks

Files added:
- plugins/projman/commands/project-init.md
- plugins/projman/commands/project-sync.md
- plugins/projman/hooks/hooks.json
- plugins/pr-review/commands/initial-setup.md
- plugins/pr-review/commands/project-init.md
- plugins/pr-review/commands/project-sync.md
- plugins/pr-review/hooks/hooks.json
- plugins/cmdb-assistant/commands/initial-setup.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Leo Miranda
2026-01-21 11:20:36 -05:00
parent 29c54279a9
commit 0c2fc8c0d9
16 changed files with 2132 additions and 401 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
CLAUDE.md
View File

@@ -28,7 +28,12 @@ A plugin marketplace for Claude Code containing:
# Validate marketplace compliance # Validate marketplace compliance
./scripts/validate-marketplace.sh ./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-plan # Start sprint planning
/sprint-status # Check progress /sprint-status # Check progress
/review # Pre-close code quality review /review # Pre-close code quality review
@@ -50,18 +55,20 @@ leo-claude-mktplace/
│ │ ├── .claude-plugin/plugin.json │ │ ├── .claude-plugin/plugin.json
│ │ ├── .mcp.json │ │ ├── .mcp.json
│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK │ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK
│ │ ├── commands/ # 9 commands │ │ ├── commands/ # 12 commands (incl. setup)
│ │ ├── hooks/ # SessionStart mismatch detection
│ │ ├── agents/ # 4 agents │ │ ├── agents/ # 4 agents
│ │ └── skills/label-taxonomy/ │ │ └── skills/label-taxonomy/
│ ├── git-flow/ # Git workflow automation (NEW v3.0.0) │ ├── git-flow/ # Git workflow automation
│ │ ├── .claude-plugin/plugin.json │ │ ├── .claude-plugin/plugin.json
│ │ ├── commands/ # 8 commands │ │ ├── commands/ # 8 commands
│ │ └── agents/ │ │ └── agents/
│ ├── pr-review/ # Multi-agent PR review (NEW v3.0.0) │ ├── pr-review/ # Multi-agent PR review
│ │ ├── .claude-plugin/plugin.json │ │ ├── .claude-plugin/plugin.json
│ │ ├── .mcp.json │ │ ├── .mcp.json
│ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK │ │ ├── mcp-servers/gitea -> ../../../mcp-servers/gitea # SYMLINK
│ │ ├── commands/ # 3 commands │ │ ├── commands/ # 6 commands (incl. setup)
│ │ ├── hooks/ # SessionStart mismatch detection
│ │ └── agents/ # 5 agents │ │ └── agents/ # 5 agents
│ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0) │ ├── clarity-assist/ # Prompt optimization (NEW v3.0.0)
│ │ ├── .claude-plugin/plugin.json │ │ ├── .claude-plugin/plugin.json
@@ -133,8 +140,10 @@ leo-claude-mktplace/
| Level | Location | Purpose | | Level | Location | Purpose |
|-------|----------|---------| |-------|----------|---------|
| System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN, GITEA_ORG) | | System | `~/.config/claude/gitea.env` | Credentials (GITEA_URL, GITEA_TOKEN) |
| Project | `.env` in project root | Repository specification (GITEA_REPO) | | 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 ### 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** | `/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** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea | | **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 | | **projman** | `/test-gen` | | X | Generate comprehensive tests for specified code |
| **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message | | **git-flow** | `/commit` | | X | Create commit with auto-generated conventional message |
| **git-flow** | `/commit-push` | | X | Commit and push to remote in one operation | | **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** | `/branch-cleanup` | | X | Remove merged branches locally and optionally on remote |
| **git-flow** | `/git-status` | | X | Enhanced git status with recommendations | | **git-flow** | `/git-status` | | X | Enhanced git status with recommendations |
| **git-flow** | `/git-config` | | X | Configure git-flow settings for the project | | **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-review` | | X | Full multi-agent PR review with confidence scoring |
| **pr-review** | `/pr-summary` | | X | Quick summary of PR changes | | **pr-review** | `/pr-summary` | | X | Quick summary of PR changes |
| **pr-review** | `/pr-findings` | | X | List and filter review findings by category/severity | | **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-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-optimize` | | X | Optimize CLAUDE.md structure with preview/backup |
| **claude-config-maintainer** | `/config-init` | | X | Initialize new CLAUDE.md for a project | | **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-search` | | X | Search NetBox for devices, IPs, sites |
| **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) | | **cmdb-assistant** | `/cmdb-device` | | X | Manage network devices (create, view, update, delete) |
| **cmdb-assistant** | `/cmdb-ip` | | X | Manage IP addresses and prefixes | | **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 | | Category | Plugins | Primary Use |
|----------|---------|-------------| |----------|---------|-------------|
| **Setup** | projman, pr-review, cmdb-assistant | `/initial-setup`, `/project-init` |
| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification | | **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews | | **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance | | **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 | | 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** | PostToolUse (Write/Edit) | Silently tracks documentation drift |
| **doc-guardian** | Stop | Prompts to sync if drift detected | | **doc-guardian** | Stop | Prompts to sync if drift detected |
| **code-sentinel** | PreToolUse (Write/Edit) | Scans for security issues; blocks critical vulnerabilities | | **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 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 1. /initial-setup # Full setup: MCP + system config + project
2. /initial-setup # Setup projman (if using) # → 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 3. /labels-sync # Sync Gitea labels
4. /sprint-plan # Plan first sprint 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 ## 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. 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: 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:** **Benefits:**
- Single token per service (update once, use everywhere) - Single token per service (update once, use everywhere)
- Easy multi-project setup (just add `.env` per project) - Easy multi-project setup (just run `/project-init` in each project)
- Security (tokens never committed to git) - Security (tokens never committed to git, never typed into AI chat)
- Project isolation (each project has its own scope) - Project isolation (each project can override defaults)
---
## Prerequisites ## Prerequisites
Before configuring any plugin: Before running `/initial-setup`:
1. **Python 3.10+** installed 1. **Python 3.10+** installed
```bash ```bash
python3 --version # Should be 3.10.0 or higher python3 --version # Should be 3.10.0 or higher
``` ```
2. **Git repository** initialized 2. **Git repository** initialized (for project setup)
```bash ```bash
git status # Should show initialized repository 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 ```bash
mkdir -p ~/.config/claude mkdir -p ~/.config/claude
```
### Gitea Configuration # Gitea configuration (credentials only)
Required by: `projman`, `pr-review`
```bash
cat > ~/.config/claude/gitea.env << 'EOF' cat > ~/.config/claude/gitea.env << 'EOF'
# Gitea API Configuration
GITEA_URL=https://gitea.example.com GITEA_URL=https://gitea.example.com
GITEA_TOKEN=your_gitea_token_here GITEA_TOKEN=your_token_here
GITEA_ORG=your_organization
EOF EOF
# Secure the file
chmod 600 ~/.config/claude/gitea.env 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 | | Variable | Description | Example |
|----------|-------------|---------| |----------|-------------|---------|
| `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` | | `GITEA_URL` | Gitea base URL (no `/api/v1`) | `https://gitea.example.com` |
| `GITEA_TOKEN` | Personal access token | `glpat-xxx...` | | `GITEA_TOKEN` | Personal access token | `abc123...` |
| `GITEA_ORG` | Organization name | `bandit` |
**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** 1. Log into Gitea → **User Icon** → **Settings**
2. **Applications** tab → **Manage Access Tokens** 2. **Applications** tab → **Manage Access Tokens**
3. **Generate New Token** with permissions: 3. **Generate New Token** with permissions:
- `repo` (all sub-permissions) - `repo` (all sub-permissions)
- `read:org` - `read:org`
- `read:user` - `read:user`
- `write:repo` (for wiki) - `write:repo` (for wiki access)
4. Copy token immediately (shown only once) 4. Copy token immediately (shown only once)
### NetBox Configuration ### NetBox Configuration
Required by: `cmdb-assistant`
```bash ```bash
cat > ~/.config/claude/netbox.env << 'EOF' # ~/.config/claude/netbox.env
# NetBox API Configuration
NETBOX_URL=https://netbox.example.com NETBOX_URL=https://netbox.example.com
NETBOX_TOKEN=your_netbox_token_here NETBOX_TOKEN=your_netbox_token_here
EOF
chmod 600 ~/.config/claude/netbox.env
``` ```
**Variables:**
| Variable | Description | Example | | Variable | Description | Example |
|----------|-------------|---------| |----------|-------------|---------|
| `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` | | `NETBOX_URL` | NetBox base URL | `https://netbox.example.com` |
@@ -95,11 +334,8 @@ chmod 600 ~/.config/claude/netbox.env
### Git-Flow Configuration ### Git-Flow Configuration
Optional system defaults for: `git-flow`
```bash ```bash
cat > ~/.config/claude/git-flow.env << 'EOF' # ~/.config/claude/git-flow.env
# Git-Flow Default Configuration
GIT_WORKFLOW_STYLE=feature-branch GIT_WORKFLOW_STYLE=feature-branch
GIT_DEFAULT_BASE=development GIT_DEFAULT_BASE=development
GIT_AUTO_DELETE_MERGED=true GIT_AUTO_DELETE_MERGED=true
@@ -107,170 +343,110 @@ GIT_AUTO_PUSH=false
GIT_PROTECTED_BRANCHES=main,master,development,staging,production GIT_PROTECTED_BRANCHES=main,master,development,staging,production
GIT_COMMIT_STYLE=conventional GIT_COMMIT_STYLE=conventional
GIT_CO_AUTHOR=true 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 ## Project-Level Configuration
Create `.env` in each project root: Create `.env` in each project root:
### Gitea Repository (projman, pr-review)
```bash ```bash
# .env in project root # Required for projman, pr-review
GITEA_ORG=your-organization
GITEA_REPO=your-repo-name GITEA_REPO=your-repo-name
```
### Git-Flow (project overrides) # Optional: Override git-flow defaults
```bash
# .env in project root
GIT_WORKFLOW_STYLE=pr-required GIT_WORKFLOW_STYLE=pr-required
GIT_DEFAULT_BASE=main GIT_DEFAULT_BASE=main
```
### PR Review # Optional: PR review settings
```bash
# .env in project root
PR_REVIEW_CONFIDENCE_THRESHOLD=0.5 PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
PR_REVIEW_AUTO_SUBMIT=false PR_REVIEW_AUTO_SUBMIT=false
``` ```
--- | Variable | Required | Description |
|----------|----------|-------------|
## MCP Server Installation | `GITEA_ORG` | Yes | Gitea organization for this project |
| `GITEA_REPO` | Yes | Repository name (must match Gitea exactly) |
MCP servers are located at repository root: `mcp-servers/` | `GIT_WORKFLOW_STYLE` | No | Override system default |
| `PR_REVIEW_*` | No | PR review settings |
### 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
```
--- ---
## Plugin Configuration Reference ## Plugin Configuration Summary
### projman | Plugin | System Config | Project Config | Setup Commands |
|--------|---------------|----------------|----------------|
| Level | Variable | Default | Description | | **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` |
| System | `GITEA_URL` | (required) | Gitea API base URL | | **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
| System | `GITEA_TOKEN` | (required) | API token | | **clarity-assist** | None | None | None needed |
| System | `GITEA_ORG` | (required) | Organization name | | **cmdb-assistant** | netbox.env | None | `/initial-setup` |
| Project | `GITEA_REPO` | (required) | Repository name | | **doc-guardian** | None | None | None needed |
| **code-sentinel** | None | None | None needed |
**Commands:** `/sprint-plan`, `/sprint-start`, `/sprint-status`, `/sprint-close`, `/labels-sync`, `/initial-setup`, `/review`, `/test-check`, `/test-gen` | **project-hygiene** | None | None | None needed |
| **claude-config-maintainer** | None | None | None needed |
### 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.
--- ---
## Multi-Project Setup ## Multi-Project Workflow
1. **System config:** Set up once (credentials) Once system-level config is set up, adding new projects is simple:
2. **Project config:** Create `.env` in each project root
**Example:** **Option 1: Use `/project-init` (faster)**
```bash
# ~/projects/my-app/.env
GITEA_REPO=my-app
# ~/projects/another-app/.env
GITEA_REPO=another-app
GIT_WORKFLOW_STYLE=trunk-based
``` ```
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 ### Test Gitea Connection
```bash ```bash
curl -H "Authorization: token YOUR_TOKEN" \ source ~/.config/claude/gitea.env
https://gitea.example.com/api/v1/user curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
``` ```
### Test MCP Server ### Verify Project Setup
```bash In Claude Code, after restarting your session:
cd mcp-servers/gitea
source .venv/bin/activate
python -c "from mcp_server import server; print('OK')"
``` ```
### Run Plugin Setup
```bash
# For projman
/initial-setup
/labels-sync /labels-sync
``` ```
If this works, your setup is complete.
--- ---
## Troubleshooting ## 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 ```bash
# Check system config exists # Check system config exists
@@ -317,23 +491,25 @@ stat ~/.config/claude/gitea.env
```bash ```bash
# Test token directly # Test token directly
curl -H "Authorization: token YOUR_TOKEN" \ source ~/.config/claude/gitea.env
https://gitea.example.com/api/v1/user curl -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
# Regenerate if invalid
``` ```
### MCP server not starting If you get 401, regenerate your token in Gitea.
### MCP server won't start
```bash ```bash
# Check venv exists # Check venv exists
ls mcp-servers/gitea/.venv ls /path/to/mcp-servers/gitea/.venv
# Reinstall if missing # Reinstall if missing
cd mcp-servers/gitea cd /path/to/mcp-servers/gitea
rm -rf .venv
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
deactivate
``` ```
### Wrong repository ### Wrong repository
@@ -342,7 +518,7 @@ pip install -r requirements.txt
# Check project .env # Check project .env
cat .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 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 - Every 6-12 months
- Immediately if compromised - Immediately if compromised
4. **Minimum permissions** 5. **Minimum permissions**
- Only grant required token permissions - Only grant required token permissions
- Use separate tokens for different environments - 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. This guide covers how to update your local installation when new versions are released.
---
## Quick Update ## Quick Update
```bash ```bash
@@ -13,12 +15,40 @@ git pull origin main
./scripts/post-update.sh ./scripts/post-update.sh
``` ```
**Then restart your Claude Code session** to load any changes.
---
## What the Post-Update Script Does ## 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 2. **Shows recent changelog entries** so you know what changed
3. **Validates your configuration** is still compatible 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 ## Manual Steps After Update
Some updates may require manual configuration changes: 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 1. Check the variable name and purpose in the changelog
2. Add it to the appropriate config file: 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 - Project variables → `.env` in your project root
### New MCP Server Features ### New MCP Server Features
@@ -37,20 +67,56 @@ If the changelog mentions new environment variables:
If a new MCP server tool is added: If a new MCP server tool is added:
1. The post-update script handles dependency installation 1. The post-update script handles dependency installation
2. Check `plugins/projman/README.md` for usage documentation 2. Check plugin documentation for usage
3. New tools are available immediately after update 3. New tools are available immediately after session restart
### Breaking Changes ### Breaking Changes
Breaking changes will be clearly marked in CHANGELOG.md with migration instructions. 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 ### Dependencies fail to install
```bash ```bash
# Rebuild virtual environment # Rebuild virtual environment
cd plugins/projman/mcp-servers/gitea cd mcp-servers/gitea
rm -rf .venv rm -rf .venv
python3 -m venv .venv python3 -m venv .venv
source .venv/bin/activate source .venv/bin/activate
@@ -61,14 +127,23 @@ deactivate
### Configuration no longer works ### Configuration no longer works
1. Check CHANGELOG.md for breaking changes 1. Check CHANGELOG.md for breaking changes
2. Compare your config files with updated `.env.example` (if provided) 2. Run `/initial-setup` to re-validate and fix configuration
3. Run `./scripts/setup.sh` to validate 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+) 1. Check Python version: `python3 --version` (requires 3.10+)
2. Verify venv exists: `ls plugins/projman/mcp-servers/gitea/.venv` 2. Verify venv exists: `ls mcp-servers/gitea/.venv`
3. Check logs for specific errors 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 ## Version Pinning
@@ -79,15 +154,28 @@ To stay on a specific version:
git tag git tag
# Checkout specific version # Checkout specific version
git checkout v2.2.0 git checkout v3.0.0
# Run post-update # Run post-update
./scripts/post-update.sh ./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 ## Getting Help
- Check `plugins/projman/README.md` for projman documentation - Check `docs/CONFIGURATION.md` for setup guide
- Check `plugins/projman/CONFIGURATION.md` for setup guide - Check `docs/COMMANDS-CHEATSHEET.md` for command reference
- Review CHANGELOG.md for recent changes - Review `CHANGELOG.md` for recent changes
- Search existing issues in Gitea - 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
``` ```
/initial-setup # First time on this machine
**Project-level** (`.env` in project root): /project-init # New project (system already configured)
```bash
GITEA_REPO=your-repo-name
``` ```
### 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 - Python 3.10+ installed
- Git repository initialized - 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 /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 /sprint-plan
``` ```
@@ -164,15 +145,40 @@ Synchronize label taxonomy from Gitea.
- When new labels are added to Gitea - When new labels are added to Gitea
### `/initial-setup` ### `/initial-setup`
Run initial setup for a new project. Full interactive setup wizard.
**What it does:** **What it does:**
- Validates Gitea MCP server connection - Checks Python version (requires 3.10+)
- Tests credential configuration - Sets up MCP server virtual environment
- Syncs label taxonomy - Creates system-level config (`~/.config/claude/gitea.env`)
- Creates required directory structure - 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` ### `/review`
Pre-sprint-close code quality review. Pre-sprint-close code quality review.

499
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 - **This command uses Bash, Read, Write, and AskUserQuestion tools** - NOT MCP tools
2. Installs all dependencies - **MCP tools won't work until after setup + session restart**
3. Creates configuration file templates - **Tokens must be entered manually by the user** for security (not typed into chat)
4. Validates existing configuration
5. Validates repository organization
6. Syncs label taxonomy
7. Reports remaining manual steps
## Execution ---
## Quick Path Detection
**FIRST**, check if system-level setup is already complete:
```bash ```bash
cd ${PROJECT_ROOT} 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"
./scripts/setup.sh
``` ```
## 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):** 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)"
**If "Quick project setup":**
- Skip directly to **Phase 4: Project-Level Configuration**
- This is equivalent to running `/project-init`
**If "Full setup":**
- Continue with Phase 1 below
**If SYSTEM_NEEDS_SETUP:**
- Continue with Phase 1 (full setup required)
---
## Phase 1: Environment Validation
### Step 1.1: Check Python Version
Run this command to verify Python 3.10+ is available:
```bash
python3 --version
``` ```
~/.config/claude/gitea.env
**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
``` ```
Contains API credentials that work across all projects.
**Project-Level (repository/paths):** If found, extract the parent path (the gitea MCP server root).
**Alternative:** If the user knows the marketplace location, ask them:
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)
### Step 2.2: Check if Virtual Environment Exists
Once you have the MCP server path (e.g., `/path/to/mcp-servers/gitea`), check for the venv:
```bash
ls -la /path/to/mcp-servers/gitea/.venv/bin/python 2>/dev/null && echo "VENV_EXISTS" || echo "VENV_MISSING"
``` ```
project-root/.env
### Step 2.3: Create Virtual Environment (if missing)
If venv doesn't exist:
```bash
cd /path/to/mcp-servers/gitea && python3 -m venv .venv
``` ```
Contains project-specific settings like repository name.
## After Running Then install dependencies:
Review the output for any manual steps required: ```bash
cd /path/to/mcp-servers/gitea && source .venv/bin/activate && pip install --upgrade pip && pip install -r requirements.txt && deactivate
```
1. **Configure API credentials** in `~/.config/claude/gitea.env`: **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:
``` ```
GITEA_URL=https://gitea.your-company.com nano ~/.config/claude/gitea.env
GITEA_TOKEN=your-api-token
GITEA_ORG=your-organization
``` ```
Or use any editor you prefer.
2. **Configure project settings** in `.env`: 2. Generate a Gitea token (if you don't have one):
``` - Go to your Gitea instance → User Icon → Settings
GITEA_REPO=your-repo-name - Click "Applications" tab
WIKIJS_PROJECT=your-project - 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. **Run `/labels-sync`** to sync Gitea labels 3. Replace `PASTE_YOUR_TOKEN_HERE` with your actual token
4. **Verify Gitea Wiki** is accessible and has proper structure 4. Save the file
## Pre-Flight Checks ---
The setup script validates: 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)"
- Repository belongs to an organization (required) **If "I need help":** Provide detailed instructions for their specific Gitea instance.
- Required label categories exist **If "Skip":** Warn that MCP tools won't work until configured, but continue with project setup.
- API credentials are valid
- Network connectivity to Gitea
## Re-Running ### Step 3.5: Validate Gitea Configuration
This command is safe to run multiple times. It will skip already-completed steps. Read the config file and verify it has non-placeholder values:
## MCP Server Structure ```bash
source ~/.config/claude/gitea.env && echo "URL: $GITEA_URL" && echo "ORG: $GITEA_ORG" && echo "TOKEN_LENGTH: ${#GITEA_TOKEN}"
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
``` ```
## Troubleshooting If TOKEN_LENGTH is less than 10 or contains "PASTE" or "your_", the token hasn't been set properly.
**Error: Repository not under organization** **Test connectivity (optional but recommended):**
- This plugin requires repositories to belong to a Gitea organization
- Transfer your repository to an organization or create one
**Error: Missing required labels** ```bash
- Run `/labels-sync` to create missing labels source ~/.config/claude/gitea.env && curl -s -o /dev/null -w "%{http_code}" -H "Authorization: token $GITEA_TOKEN" "$GITEA_URL/api/v1/user"
- Or create them manually in Gitea ```
**Error: Cannot connect to Gitea** - **200:** Success! Credentials are valid.
- Verify `GITEA_URL` in `~/.config/claude/gitea.env` - **401:** Invalid token.
- Check your API token has proper permissions - **404/Connection error:** Invalid URL or network issue.
- Ensure network connectivity
**Error: Virtual environment creation failed** Report the result to the user.
- Ensure Python 3.8+ is installed
- Check disk space ### Step 3.6: Git-Flow Configuration (Optional)
- Try running `python -m venv .venv` manually in the MCP server directory
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 #!/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 # Usage: ./scripts/setup.sh
# #