personal-projects/leo-claude-mktplace
Template
0
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2c41ca338d705a2bd94607e4e5803aa2112c6c51
leo-claude-mktplace/docs/CONFIGURATION.md

30 KiB
Raw Blame History

Configuration Guide

Centralized configuration documentation for all plugins and MCP servers in the Leo Claude Marketplace.

Quick Start

After installing the marketplace and plugins via Claude Code:

/pm-setup

The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.

Setup Flow Diagram

┌─────────────────────────────────────────────────────────────────────────────┐
│                           FIRST TIME SETUP                                  │
│                         (once per machine)                                  │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                             /pm-setup --full
                         (or /pm-setup auto-detects)
                                    │
     ┌──────────────────────────────┼──────────────────────────────┐
     ▼                              ▼                              ▼
┌─────────────┐            ┌─────────────────┐            ┌─────────────────┐
│  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)                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
            /pm-setup --quick                  /pm-setup
             (explicit mode)               (auto-detects mode)
                    │                               │
                    │                    ┌──────────┴──────────┐
                    │                    ▼                     ▼
                    │              "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

/pm-setup --full - 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

/pm-setup --quick - 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

One Command, Three Modes

Mode When to Use What It Does
/pm-setup Any time Auto-detects: runs full, quick, or sync as needed
/pm-setup --full First time on a machine Full setup: MCP server + system config + project config
/pm-setup --quick Starting a new project Quick setup: project config only (assumes system is ready)
/pm-setup --sync After repo move/rename Updates .env to match current git remote

Auto-detection logic:

  1. No system config → full mode
  2. System config exists, no project config → quick mode
  3. Both exist, git remote differs → sync mode
  4. Both exist, match → already configured, offer to reconfigure

Typical workflow:

  1. Install plugin → run /pm-setup (auto-runs full mode)
  2. Start new project → run /pm-setup (auto-runs quick mode)
  3. Repository moved? → run /pm-setup (auto-runs sync mode)

Configuration Architecture

This marketplace uses a hybrid configuration approach:

┌─────────────────────────────────────────────────────────────────┐
│                    SYSTEM-LEVEL (once per machine)             │
│                    ~/.config/claude/                            │
├─────────────────────────────────────────────────────────────────┤
│  gitea.env     │  GITEA_API_URL, GITEA_API_TOKEN                       │
│  netbox.env    │  NETBOX_API_URL, NETBOX_API_TOKEN                     │
│  git-flow.env  │  GIT_WORKFLOW_STYLE, GIT_DEFAULT_BASE, etc.   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ Shared across all projects
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  PROJECT-LEVEL (once per project)              │
│                  <project-root>/.env                            │
├─────────────────────────────────────────────────────────────────┤
│  GITEA_REPO              │  Repository as owner/repo format    │
│  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 run /pm-setup in each project)
  • Security (tokens never committed to git, never typed into AI chat)
  • Project isolation (each project can override defaults)

Prerequisites

Before running /pm-setup:

  1. Python 3.10+ installed

    python3 --version  # Should be 3.10.0 or higher

  2. Git repository initialized (for project setup)

    git status  # Should show initialized repository

  3. Claude Code installed and working with the marketplace

Setup Methods

Method 1: Interactive Wizard (Recommended)

Run the setup wizard in Claude Code:

/pm-setup

The wizard will guide you through each step interactively and auto-detect the appropriate mode.

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

# 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

mkdir -p ~/.config/claude

# Gitea configuration (credentials only)
cat > ~/.config/claude/gitea.env << 'EOF'
GITEA_API_URL=https://gitea.example.com
GITEA_API_TOKEN=your_token_here
EOF
chmod 600 ~/.config/claude/gitea.env

Step 3: Project Configuration

In each project root:

cat > .env << 'EOF'
GITEA_REPO=your-organization/your-repo-name
EOF

Add .env to .gitignore if not already there.

Method 3: Automation Script (CI/Scripting)

For automated setups or CI environments:

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

# ~/.config/claude/gitea.env
GITEA_API_URL=https://gitea.example.com/api/v1
GITEA_API_TOKEN=your_gitea_token_here
Variable Description Example
GITEA_API_URL Gitea API endpoint (with /api/v1) https://gitea.example.com/api/v1
GITEA_API_TOKEN Personal access token abc123...

Note: GITEA_REPO is configured at the project level in owner/repo format 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 access)
  4. Copy token immediately (shown only once)

NetBox Configuration

# ~/.config/claude/netbox.env
NETBOX_API_URL=https://netbox.example.com
NETBOX_API_TOKEN=your_netbox_token_here
Variable Description Example
NETBOX_API_URL NetBox base URL https://netbox.example.com
NETBOX_API_TOKEN API token abc123...

Git-Flow Configuration

# ~/.config/claude/git-flow.env
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
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:

# Required for projman, pr-review (use owner/repo format)
GITEA_REPO=your-organization/your-repo-name

# Optional: Override git-flow defaults
GIT_WORKFLOW_STYLE=pr-required
GIT_DEFAULT_BASE=main

# Optional: PR review settings
PR_REVIEW_CONFIDENCE_THRESHOLD=0.5
PR_REVIEW_AUTO_SUBMIT=false
Variable Required Description
GITEA_REPO Yes Repository in owner/repo format (e.g., my-org/my-repo)
GIT_WORKFLOW_STYLE No Override system default
PR_REVIEW_* No PR review settings

Plugin Configuration Summary

Plugin System Config Project Config Setup Command
projman gitea.env .env (GITEA_REPO=owner/repo) /pm-setup
pr-review gitea.env .env (GITEA_REPO=owner/repo) /pr-setup
git-flow git-flow.env (optional) .env (optional) None needed
clarity-assist None None None needed
cmdb-assistant netbox.env None /cmdb-setup
data-platform postgres.env .env (optional) /data-setup
viz-platform None .env (optional DMC_VERSION) /viz-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
contract-validator None None /cv-setup

Multi-Project Workflow

Once system-level config is set up, adding new projects is simple:

cd ~/projects/new-project
/pm-setup

The command auto-detects that system config exists and runs quick project setup.

Installing Plugins to Consumer Projects

The marketplace provides scripts to install plugins into consumer projects. This sets up the MCP server connections and adds CLAUDE.md integration snippets.

Install a Plugin

cd /path/to/leo-claude-mktplace
./scripts/install-plugin.sh <plugin-name> <target-project-path>

Examples:

# Install data-platform to a portfolio project
./scripts/install-plugin.sh data-platform ~/projects/personal-portfolio

# Install multiple plugins
./scripts/install-plugin.sh viz-platform ~/projects/personal-portfolio
./scripts/install-plugin.sh projman ~/projects/personal-portfolio

What it does:

  1. Validates the plugin exists in the marketplace
  2. Adds MCP server entry to target's .mcp.json (if plugin has MCP server)
  3. Appends integration snippet to target's CLAUDE.md
  4. Reports changes and lists available commands

After installation: Restart your Claude Code session for MCP tools to become available.

Uninstall a Plugin

./scripts/uninstall-plugin.sh <plugin-name> <target-project-path>

Removes the MCP server entry and CLAUDE.md integration section.

List Installed Plugins

./scripts/list-installed.sh <target-project-path>

Shows which marketplace plugins are installed, partially installed, or available.

Output example:

✓ Fully Installed:
  PLUGIN                   VERSION    DESCRIPTION
  ------                   -------    -----------
  data-platform            1.3.0      pandas, PostgreSQL, and dbt integration...
  viz-platform             1.1.0      DMC validation, Plotly charts, and theming...

○ Available (not installed):
  projman                  3.4.0      Sprint planning and project management...

Plugins with MCP Servers

Not all plugins have MCP servers. The install script handles this automatically:

Plugin Has MCP Server Notes
data-platform ✓ pandas, PostgreSQL, dbt tools
viz-platform ✓ DMC validation, chart, theme tools
contract-validator ✓ Plugin compatibility validation
cmdb-assistant ✓ (via netbox) NetBox CMDB tools
projman ✓ (via gitea) Issue, wiki, PR tools
pr-review ✓ (via gitea) PR review tools
git-flow ✗ Commands only
doc-guardian ✗ Commands and hooks only
code-sentinel ✗ Commands and hooks only
clarity-assist ✗ Commands only

Script Requirements

  • jq must be installed (sudo apt install jq)
  • Scripts are idempotent (safe to run multiple times)

Agent Frontmatter Configuration

Agents specify their configuration in frontmatter using Claude Code's supported fields. Reference: https://code.claude.com/docs/en/sub-agents

Supported Frontmatter Fields

Field Required Default Description
name Yes — Unique identifier, lowercase + hyphens
description Yes — When Claude should delegate to this subagent
model No inherit sonnet, opus, haiku, or inherit
permissionMode No default Controls permission prompts: default, acceptEdits, dontAsk, bypassPermissions, plan
disallowedTools No none Comma-separated tools to remove from agent's toolset
skills No none Comma-separated skills auto-injected into context at startup
hooks No none Lifecycle hooks scoped to this subagent

Complete Agent Matrix

Plugin Agent model permissionMode disallowedTools skills
projman planner opus default — frontmatter (2) + body text (12)
projman orchestrator sonnet acceptEdits — frontmatter (2) + body text (10)
projman executor sonnet bypassPermissions — frontmatter (7)
projman code-reviewer opus default Write, Edit, MultiEdit frontmatter (4)
pr-review coordinator sonnet plan Write, Edit, MultiEdit —
pr-review security-reviewer sonnet plan Write, Edit, MultiEdit —
pr-review performance-analyst sonnet plan Write, Edit, MultiEdit —
pr-review maintainability-auditor haiku plan Write, Edit, MultiEdit —
pr-review test-validator haiku plan Write, Edit, MultiEdit —
data-platform data-advisor sonnet default — —
data-platform data-analysis sonnet plan Write, Edit, MultiEdit —
data-platform data-ingestion haiku acceptEdits — —
viz-platform design-reviewer sonnet plan Write, Edit, MultiEdit —
viz-platform layout-builder sonnet default — —
viz-platform component-check haiku plan Write, Edit, MultiEdit —
viz-platform theme-setup haiku acceptEdits — —
contract-validator full-validation sonnet default — —
contract-validator agent-check haiku plan Write, Edit, MultiEdit —
code-sentinel security-reviewer sonnet plan Write, Edit, MultiEdit —
code-sentinel refactor-advisor sonnet acceptEdits — —
doc-guardian doc-analyzer sonnet acceptEdits — —
clarity-assist clarity-coach sonnet default Write, Edit, MultiEdit —
git-flow git-assistant haiku acceptEdits — —
claude-config-maintainer maintainer sonnet acceptEdits — frontmatter (2)
cmdb-assistant cmdb-assistant sonnet default — —

Design Principles

  • bypassPermissions is granted to exactly ONE agent (Executor) which has code-sentinel PreToolUse hook + Code Reviewer downstream as safety nets.
  • plan mode is assigned to all pure analysis agents (pr-review, read-only validators).
  • disallowedTools: Write, Edit, MultiEdit provides defense-in-depth on agents that should never write files.
  • skills frontmatter is used for agents with ≤7 skills where guaranteed loading is safety-critical. Agents with 8+ skills use body text ## Skills to Load for selective loading.
  • hooks (agent-scoped) is reserved for future use (v6.0+).

Override any field by editing the agent's .md file in plugins/{plugin}/agents/.

permissionMode Guide

Value Prompts for file ops? Prompts for Bash? Prompts for MCP? Use when
default Yes Yes No (MCP bypasses permissions) You want full visibility
acceptEdits No Yes No Core job is file read/write, Bash visibility useful
dontAsk No No (most) No Even Bash prompts are friction
bypassPermissions No No No Agent has downstream safety layers
plan N/A (read-only) N/A (read-only) No Pure analysis, no modifications

disallowedTools Guide

Use disallowedTools to remove specific tools from an agent's toolset. This is a blacklist — the agent inherits all tools from the main thread, then the listed tools are removed.

Prefer disallowedTools over tools (whitelist) because:

  • New MCP servers are automatically available without updating every agent.
  • Less configuration to maintain.
  • Easier to audit — you only list what's blocked.

Common patterns:

  • disallowedTools: Write, Edit, MultiEdit — read-only agent, cannot modify files.
  • disallowedTools: Bash — no shell access (rare, most agents need at least read-only Bash).

skills Frontmatter Guide

The skills field auto-injects skill file contents into the agent's context window at startup. The agent does NOT need to read the files — they are already present.

When to use frontmatter skills:

  • Agent has ≤7 skills.
  • Skills are safety-critical (e.g., branch-security, runaway-detection).
  • You need guaranteed loading — no risk of the agent skipping a skill.

When to keep body text ## Skills to Load:

  • Agent has 8+ skills (context window cost too high for full injection).
  • Skills are situational — not all needed for every invocation.
  • Agent benefits from selective loading based on the specific task.

Skill names in frontmatter are resolved relative to the plugin's skills/ directory. Use the filename without the .md extension.

Phase-Based Skill Loading (Body Text)

For agents with 8+ skills, use phase-based loading in the agent body text. This structures skill reads into logical phases, with explicit instructions to read each skill exactly once.

Pattern:

## Skill Loading Protocol

**Frontmatter skills (auto-injected, always available — DO NOT re-read these):**
- `skill-a` — description
- `skill-b` — description

**Phase 1 skills — read ONCE at session start:**
- skills/validation-skill.md
- skills/safety-skill.md

**Phase 2 skills — read ONCE when entering main work:**
- skills/workflow-skill.md
- skills/domain-skill.md

**CRITICAL: Read each skill file exactly ONCE. Do NOT re-read skill files between MCP API calls.**

Benefits:

  • Frontmatter skills (always needed) are auto-injected — zero file read cost
  • Phase skills are read once at the appropriate time — not re-read per API call
  • batch-execution skill provides protocol for API-heavy phases
  • ~76-83% reduction in skill-related token consumption for typical sprints

Currently applied to:

  • Planner agent: 2 frontmatter + 12 body text (3 phases)
  • Orchestrator agent: 2 frontmatter + 10 body text (2 phases)

Automatic Validation Features

API Validation

When running /pm-setup, the command:

  1. Detects organization and repository from git remote URL
  2. Validates via Gitea API: GET /api/v1/repos/{org}/{repo}
  3. Auto-fills if repository exists and is accessible (no confirmation needed)
  4. Asks 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_REPO (in owner/repo format) from .env
  2. Compares with current git remote get-url origin
  3. Warns if mismatch detected: "Repository location mismatch. Run /pm-setup --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

Verification

Test Gitea Connection

source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"

Verify Project Setup

In Claude Code, after restarting your session:

/labels-sync

If this works, your setup is complete.

Troubleshooting

MCP tools not available

Cause: Session wasn't restarted after setup. Solution: Exit Claude Code and start a new session.

"Configuration not found" error

# Check system config exists
ls -la ~/.config/claude/gitea.env

# Check permissions (should be 600)
stat ~/.config/claude/gitea.env

Authentication failed

# Test token directly
source ~/.config/claude/gitea.env
curl -H "Authorization: token $GITEA_API_TOKEN" "$GITEA_API_URL/user"

If you get 401, regenerate your token in Gitea.

MCP server won't start

# Check venv exists
ls /path/to/mcp-servers/gitea/.venv

# If missing, create venv (do NOT delete existing venvs)
cd /path/to/mcp-servers/gitea
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
deactivate

Wrong repository

# Check project .env
cat .env

# Verify GITEA_REPO is in owner/repo format and matches Gitea exactly
# Example: GITEA_REPO=my-org/my-repo

Security Best Practices

  1. Never commit tokens

    • Keep credentials in ~/.config/claude/ only
    • Add .env to .gitignore

  2. Secure configuration files

    chmod 600 ~/.config/claude/*.env

  3. Never type tokens into AI chat

    • Always edit config files directly in your editor
    • The /pm-setup wizard respects this

  4. Rotate tokens periodically

    • Every 6-12 months
    • Immediately if compromised

  5. Minimum permissions

    • Only grant required token permissions
    • Use separate tokens for different environments
Reference in New Issue View Git Blame Copy Permalink