refactor(projman): extract skills and consolidate commands
Major refactoring of projman plugin architecture: Skills Extraction (17 new files): - Extracted reusable knowledge from commands and agents into skills/ - branch-security, dependency-management, git-workflow, input-detection - issue-conventions, lessons-learned, mcp-tools-reference, planning-workflow - progress-tracking, repo-validation, review-checklist, runaway-detection - setup-workflows, sprint-approval, task-sizing, test-standards, wiki-conventions Command Consolidation (17 → 12 commands): - /setup: consolidates initial-setup, project-init, project-sync (--full/--quick/--sync) - /debug: consolidates debug-report, debug-review (report/review modes) - /test: consolidates test-check, test-gen (run/gen modes) - /sprint-status: absorbs sprint-diagram via --diagram flag Architecture Cleanup: - Remove plugin-level mcp-servers/ symlinks (6 plugins) - Remove plugin README.md files (12 files, ~2000 lines) - Update all documentation to reflect new command structure - Fix documentation drift in CONFIGURATION.md, COMMANDS-CHEATSHEET.md Commands are now thin dispatchers (~20-50 lines) that reference skills. Agents reference skills for domain knowledge instead of inline content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
**This file defines ALL valid paths in this repository. No exceptions. No inference. No assumptions.**
|
||||
|
||||
Last Updated: 2026-01-27 (v5.1.0)
|
||||
Last Updated: 2026-01-30 (v5.5.0)
|
||||
|
||||
---
|
||||
|
||||
@@ -76,9 +76,6 @@ leo-claude-mktplace/
|
||||
├── plugins/ # ALL plugins
|
||||
│ ├── projman/ # Sprint management
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── gitea -> ../../../mcp-servers/gitea # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
@@ -99,9 +96,6 @@ leo-claude-mktplace/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── cmdb-assistant/ # NetBox CMDB integration
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── netbox -> ../../../mcp-servers/netbox # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md
|
||||
@@ -114,49 +108,37 @@ leo-claude-mktplace/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── clarity-assist/ # NEW in v3.0.0
|
||||
│ ├── clarity-assist/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── git-flow/ # NEW in v3.0.0
|
||||
│ ├── git-flow/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── pr-review/ # NEW in v3.0.0
|
||||
│ ├── pr-review/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── gitea -> ../../../mcp-servers/gitea # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── skills/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── data-platform/ # NEW in v4.0.0
|
||||
│ ├── data-platform/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── data-platform -> ../../../mcp-servers/data-platform # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ ├── hooks/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ ├── contract-validator/ # NEW in v5.0.0
|
||||
│ ├── contract-validator/
|
||||
│ │ ├── .claude-plugin/
|
||||
│ │ ├── .mcp.json
|
||||
│ │ ├── mcp-servers/
|
||||
│ │ │ └── contract-validator -> ../../../mcp-servers/contract-validator # SYMLINK
|
||||
│ │ ├── commands/
|
||||
│ │ ├── agents/
|
||||
│ │ └── claude-md-integration.md
|
||||
│ └── viz-platform/ # NEW in v4.1.0
|
||||
│ └── viz-platform/
|
||||
│ ├── .claude-plugin/
|
||||
│ ├── .mcp.json
|
||||
│ ├── mcp-servers/
|
||||
│ │ └── viz-platform -> ../../../mcp-servers/viz-platform # SYMLINK
|
||||
│ ├── commands/
|
||||
│ ├── agents/
|
||||
│ ├── hooks/
|
||||
@@ -188,29 +170,21 @@ leo-claude-mktplace/
|
||||
| Plugin manifest | `plugins/{plugin-name}/.claude-plugin/plugin.json` | `plugins/projman/.claude-plugin/plugin.json` |
|
||||
| Plugin commands | `plugins/{plugin-name}/commands/` | `plugins/projman/commands/` |
|
||||
| Plugin agents | `plugins/{plugin-name}/agents/` | `plugins/projman/agents/` |
|
||||
| Plugin .mcp.json | `plugins/{plugin-name}/.mcp.json` | `plugins/projman/.mcp.json` |
|
||||
| Plugin skills | `plugins/{plugin-name}/skills/` | `plugins/projman/skills/` |
|
||||
| Plugin integration snippet | `plugins/{plugin-name}/claude-md-integration.md` | `plugins/projman/claude-md-integration.md` |
|
||||
|
||||
### MCP Server Paths (v3.0.0 Architecture)
|
||||
### MCP Server Paths
|
||||
|
||||
MCP servers are **shared at repository root** with **symlinks** from plugins.
|
||||
MCP servers are **shared at repository root** and configured in `.mcp.json`.
|
||||
|
||||
| Context | Pattern | Example |
|
||||
|---------|---------|---------|
|
||||
| MCP configuration | `.mcp.json` | `.mcp.json` (at repo root) |
|
||||
| Shared MCP server | `mcp-servers/{server}/` | `mcp-servers/gitea/` |
|
||||
| MCP server code | `mcp-servers/{server}/mcp_server/` | `mcp-servers/gitea/mcp_server/` |
|
||||
| MCP venv | `mcp-servers/{server}/.venv/` | `mcp-servers/gitea/.venv/` |
|
||||
| Plugin symlink | `plugins/{plugin}/mcp-servers/{server}` | `plugins/projman/mcp-servers/gitea` |
|
||||
|
||||
### Symlink Pattern
|
||||
|
||||
Plugins that use MCP servers create symlinks:
|
||||
```bash
|
||||
# From plugin directory
|
||||
ln -s ../../../mcp-servers/gitea plugins/projman/mcp-servers/gitea
|
||||
```
|
||||
|
||||
The symlink target is relative: `../../../mcp-servers/{server}`
|
||||
**Note:** Plugins do NOT have their own `mcp-servers/` directories. All MCP servers are shared at root and configured via `.mcp.json`.
|
||||
|
||||
### Documentation Paths
|
||||
|
||||
@@ -239,15 +213,12 @@ The symlink target is relative: `../../../mcp-servers/{server}`
|
||||
2. Verify each path against patterns in this file
|
||||
3. Show verification to user before proceeding
|
||||
|
||||
### Relative Path Calculation (v3.0.0)
|
||||
### Relative Path Calculation
|
||||
|
||||
From `plugins/projman/.mcp.json` to shared `mcp-servers/gitea/`:
|
||||
From `.mcp.json` (at root) to `mcp-servers/gitea/`:
|
||||
```
|
||||
plugins/projman/.mcp.json
|
||||
→ Uses ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/
|
||||
→ Symlink at plugins/projman/mcp-servers/gitea points to ../../../mcp-servers/gitea
|
||||
|
||||
Result in .mcp.json: ${CLAUDE_PLUGIN_ROOT}/mcp-servers/gitea/.venv/bin/python
|
||||
.mcp.json (at repository root)
|
||||
→ Uses absolute installed path: ~/.claude/plugins/marketplaces/.../mcp-servers/gitea/run.sh
|
||||
```
|
||||
|
||||
From `.claude-plugin/marketplace.json` to `plugins/projman/`:
|
||||
@@ -266,30 +237,34 @@ Result: ./plugins/projman
|
||||
| Wrong | Why | Correct |
|
||||
|-------|-----|---------|
|
||||
| `projman/` at root | Plugins go in `plugins/` | `plugins/projman/` |
|
||||
| Direct path in .mcp.json to root mcp-servers | Use symlink | Symlink at `plugins/{plugin}/mcp-servers/` |
|
||||
| Creating new mcp-servers inside plugins | Use shared + symlink | Symlink to `mcp-servers/` |
|
||||
| Hardcoding absolute paths | Breaks portability | Use `${CLAUDE_PLUGIN_ROOT}` |
|
||||
| `mcp-servers/` inside plugins | MCP servers are shared at root | Use root `mcp-servers/` |
|
||||
| Plugin-level `.mcp.json` | MCP config is at root | Use root `.mcp.json` |
|
||||
| Hardcoding absolute paths in source | Breaks portability | Use relative paths or `${CLAUDE_PLUGIN_ROOT}` |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Note (v3.0.0)
|
||||
## Architecture Note
|
||||
|
||||
MCP servers are now **shared at repository root** with **symlinks** from plugins:
|
||||
MCP servers are **shared at repository root** and configured in a single `.mcp.json` file.
|
||||
|
||||
**Benefits:**
|
||||
- Single source of truth for each MCP server
|
||||
- Updates apply to all plugins automatically
|
||||
- Reduced duplication
|
||||
- Symlinks work with Claude Code caching
|
||||
- No duplication - clean plugin structure
|
||||
- Simple configuration in one place
|
||||
|
||||
**Symlink Pattern:**
|
||||
```
|
||||
plugins/projman/mcp-servers/gitea -> ../../../mcp-servers/gitea
|
||||
plugins/cmdb-assistant/mcp-servers/netbox -> ../../../mcp-servers/netbox
|
||||
plugins/pr-review/mcp-servers/gitea -> ../../../mcp-servers/gitea
|
||||
plugins/data-platform/mcp-servers/data-platform -> ../../../mcp-servers/data-platform
|
||||
plugins/viz-platform/mcp-servers/viz-platform -> ../../../mcp-servers/viz-platform
|
||||
plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-servers/contract-validator
|
||||
**Configuration:**
|
||||
All MCP servers are defined in `.mcp.json` at repository root:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"gitea": { "command": ".../mcp-servers/gitea/run.sh" },
|
||||
"netbox": { "command": ".../mcp-servers/netbox/run.sh" },
|
||||
"data-platform": { "command": ".../mcp-servers/data-platform/run.sh" },
|
||||
"viz-platform": { "command": ".../mcp-servers/viz-platform/run.sh" },
|
||||
"contract-validator": { "command": ".../mcp-servers/contract-validator/run.sh" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
@@ -298,6 +273,7 @@ plugins/contract-validator/mcp-servers/contract-validator -> ../../../mcp-server
|
||||
|
||||
| Date | Change | By |
|
||||
|------|--------|-----|
|
||||
| 2026-01-30 | v5.5.0: Removed plugin-level mcp-servers symlinks - all MCP config now in root .mcp.json | Claude Code |
|
||||
| 2026-01-26 | v5.0.0: Added contract-validator plugin and MCP server | Claude Code |
|
||||
| 2026-01-26 | v4.1.0: Added viz-platform plugin and MCP server | Claude Code |
|
||||
| 2026-01-25 | v4.0.0: Added data-platform plugin and MCP server | Claude Code |
|
||||
|
||||
@@ -10,21 +10,17 @@ Quick reference for all commands in the Leo Claude Marketplace.
|
||||
|--------|---------|:----:|:------:|-------------|
|
||||
| **projman** | `/sprint-plan` | | X | Start sprint planning with AI-guided architecture analysis and issue creation |
|
||||
| **projman** | `/sprint-start` | | X | Begin sprint execution with dependency analysis and parallel task coordination |
|
||||
| **projman** | `/sprint-status` | | X | Check current sprint progress and identify blockers |
|
||||
| **projman** | `/sprint-status` | | X | Check current sprint progress (add `--diagram` for Mermaid visualization) |
|
||||
| **projman** | `/review` | | X | Pre-sprint-close code quality review (debug artifacts, security, error handling) |
|
||||
| **projman** | `/test-check` | | X | Run tests and verify coverage before sprint close |
|
||||
| **projman** | `/test` | | X | Run tests (`/test run`) or generate tests (`/test gen <target>`) |
|
||||
| **projman** | `/sprint-close` | | X | Complete sprint and capture lessons learned to Gitea Wiki |
|
||||
| **projman** | `/labels-sync` | | X | Synchronize label taxonomy from Gitea |
|
||||
| **projman** | `/initial-setup` | | X | 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** | `/debug-report` | | X | Run diagnostics and create structured issue in marketplace |
|
||||
| **projman** | `/debug-review` | | X | Investigate diagnostic issues and propose fixes with approval gates |
|
||||
| **projman** | `/setup` | | X | Auto-detect mode or use `--full`, `--quick`, `--sync` |
|
||||
| **projman** | *SessionStart hook* | X | | Detects git remote vs .env mismatch, warns to run `/setup --sync` |
|
||||
| **projman** | `/debug` | | X | Diagnostics (`/debug report`) or investigate (`/debug review`) |
|
||||
| **projman** | `/suggest-version` | | X | Analyze CHANGELOG and recommend semantic version bump |
|
||||
| **projman** | `/proposal-status` | | X | View proposal and implementation hierarchy with status |
|
||||
| **projman** | `/sprint-diagram` | | X | Generate Mermaid diagram of sprint issues with dependencies |
|
||||
| **projman** | `/clear-cache` | | X | Clear plugin cache to force fresh configuration reload |
|
||||
| **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-merge` | | X | Commit current changes, then merge into target branch |
|
||||
@@ -104,7 +100,7 @@ Quick reference for all commands in the Leo Claude Marketplace.
|
||||
|
||||
| Category | Plugins | Primary Use |
|
||||
|----------|---------|-------------|
|
||||
| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/initial-setup`, `/project-init` |
|
||||
| **Setup** | projman, pr-review, cmdb-assistant, data-platform | `/setup`, `/initial-setup` |
|
||||
| **Task Planning** | projman, clarity-assist | Sprint management, requirement clarification |
|
||||
| **Code Quality** | code-sentinel, pr-review | Security scanning, PR reviews |
|
||||
| **Documentation** | doc-guardian, claude-config-maintainer | Doc sync, CLAUDE.md maintenance |
|
||||
@@ -145,9 +141,9 @@ A typical workflow for planning and executing a feature sprint:
|
||||
5. /branch-start feat/... # Create feature branch
|
||||
... implement features ...
|
||||
6. /commit # Commit with conventional message
|
||||
7. /sprint-status # Check progress mid-sprint
|
||||
7. /sprint-status --diagram # Check progress with visualization
|
||||
8. /review # Pre-close quality review
|
||||
9. /test-check # Verify test coverage
|
||||
9. /test run # Verify test coverage
|
||||
10. /sprint-close # Capture lessons learned
|
||||
```
|
||||
|
||||
@@ -194,7 +190,7 @@ Safe refactoring with preview:
|
||||
1. /refactor-dry # Preview opportunities
|
||||
2. /security-scan # Baseline security check
|
||||
3. /refactor # Apply improvements
|
||||
4. /test-check # Verify nothing broke
|
||||
4. /test run # Verify nothing broke
|
||||
5. /commit # Commit with descriptive message
|
||||
```
|
||||
|
||||
@@ -227,7 +223,7 @@ Working with data pipelines:
|
||||
Setting up the marketplace for the first time:
|
||||
|
||||
```
|
||||
1. /initial-setup # Full setup: MCP + system config + project
|
||||
1. /setup --full # Full setup: MCP + system config + project
|
||||
# → Follow prompts for Gitea URL, org
|
||||
# → Add token manually when prompted
|
||||
# → Confirm repository name
|
||||
@@ -241,7 +237,7 @@ Setting up the marketplace for the first time:
|
||||
Adding a new project when system config exists:
|
||||
|
||||
```
|
||||
1. /project-init # Quick project setup
|
||||
1. /setup --quick # Quick project setup (auto-detected)
|
||||
# → Confirms detected repo name
|
||||
# → Creates .env
|
||||
2. /labels-sync # Sync Gitea labels
|
||||
@@ -277,4 +273,4 @@ Ensure credentials are configured in `~/.config/claude/gitea.env`, `~/.config/cl
|
||||
|
||||
---
|
||||
|
||||
*Last Updated: 2026-01-28*
|
||||
*Last Updated: 2026-01-30*
|
||||
|
||||
@@ -9,10 +9,10 @@ Centralized configuration documentation for all plugins and MCP servers in the L
|
||||
**After installing the marketplace and plugins via Claude Code:**
|
||||
|
||||
```
|
||||
/initial-setup
|
||||
/setup
|
||||
```
|
||||
|
||||
The interactive wizard handles everything except manually adding your API tokens.
|
||||
The interactive wizard auto-detects what's needed and handles everything except manually adding your API tokens.
|
||||
|
||||
---
|
||||
|
||||
@@ -25,7 +25,8 @@ The interactive wizard handles everything except manually adding your API tokens
|
||||
└─────────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
/initial-setup
|
||||
/setup --full
|
||||
(or /setup auto-detects)
|
||||
│
|
||||
┌──────────────────────────────┼──────────────────────────────┐
|
||||
▼ ▼ ▼
|
||||
@@ -78,8 +79,8 @@ The interactive wizard handles everything except manually adding your API tokens
|
||||
│
|
||||
┌───────────────┴───────────────┐
|
||||
▼ ▼
|
||||
/project-init /initial-setup
|
||||
(direct path) (smart detection)
|
||||
/setup --quick /setup
|
||||
(explicit mode) (auto-detects mode)
|
||||
│ │
|
||||
│ ┌──────────┴──────────┐
|
||||
│ ▼ ▼
|
||||
@@ -108,7 +109,7 @@ The interactive wizard handles everything except manually adding your API tokens
|
||||
|
||||
## What Runs Automatically vs User Interaction
|
||||
|
||||
### `/initial-setup` - Full Setup
|
||||
### `/setup --full` - Full Setup
|
||||
|
||||
| Phase | Type | What Happens |
|
||||
|-------|------|--------------|
|
||||
@@ -120,7 +121,7 @@ The interactive wizard handles everything except manually adding your API tokens
|
||||
| **6. Project Config** | Automated | Creates `.env` file, checks `.gitignore` |
|
||||
| **7. Validation** | Automated | Tests API connectivity, shows summary |
|
||||
|
||||
### `/project-init` - Quick Project Setup
|
||||
### `/setup --quick` - Quick Project Setup
|
||||
|
||||
| Phase | Type | What Happens |
|
||||
|-------|------|--------------|
|
||||
@@ -131,23 +132,25 @@ The interactive wizard handles everything except manually adding your API tokens
|
||||
|
||||
---
|
||||
|
||||
## Three Commands for Different Scenarios
|
||||
## One Command, Three Modes
|
||||
|
||||
| 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 |
|
||||
| Mode | When to Use | What It Does |
|
||||
|------|-------------|--------------|
|
||||
| `/setup` | Any time | Auto-detects: runs full, quick, or sync as needed |
|
||||
| `/setup --full` | First time on a machine | Full setup: MCP server + system config + project config |
|
||||
| `/setup --quick` | Starting a new project | Quick setup: project config only (assumes system is ready) |
|
||||
| `/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 `/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
|
||||
1. Install plugin → run `/setup` (auto-runs full mode)
|
||||
2. Start new project → run `/setup` (auto-runs quick mode)
|
||||
3. Repository moved? → run `/setup` (auto-runs sync mode)
|
||||
|
||||
---
|
||||
|
||||
@@ -179,7 +182,7 @@ This marketplace uses a **hybrid configuration** approach:
|
||||
|
||||
**Benefits:**
|
||||
- Single token per service (update once, use everywhere)
|
||||
- Easy multi-project setup (just run `/project-init` in each project)
|
||||
- Easy multi-project setup (just run `/setup` in each project)
|
||||
- Security (tokens never committed to git, never typed into AI chat)
|
||||
- Project isolation (each project can override defaults)
|
||||
|
||||
@@ -187,7 +190,7 @@ This marketplace uses a **hybrid configuration** approach:
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before running `/initial-setup`:
|
||||
Before running `/setup`:
|
||||
|
||||
1. **Python 3.10+** installed
|
||||
```bash
|
||||
@@ -210,10 +213,10 @@ Before running `/initial-setup`:
|
||||
Run the setup wizard in Claude Code:
|
||||
|
||||
```
|
||||
/initial-setup
|
||||
/setup
|
||||
```
|
||||
|
||||
The wizard will guide you through each step interactively.
|
||||
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.
|
||||
|
||||
@@ -382,10 +385,10 @@ PR_REVIEW_AUTO_SUBMIT=false
|
||||
|
||||
## Plugin Configuration Summary
|
||||
|
||||
| Plugin | System Config | Project Config | Setup Commands |
|
||||
|--------|---------------|----------------|----------------|
|
||||
| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
|
||||
| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup`, `/project-init`, `/project-sync` |
|
||||
| Plugin | System Config | Project Config | Setup Command |
|
||||
|--------|---------------|----------------|---------------|
|
||||
| **projman** | gitea.env | .env (GITEA_REPO=owner/repo) | `/setup` |
|
||||
| **pr-review** | gitea.env | .env (GITEA_REPO=owner/repo) | `/initial-setup` |
|
||||
| **git-flow** | git-flow.env (optional) | .env (optional) | None needed |
|
||||
| **clarity-assist** | None | None | None needed |
|
||||
| **cmdb-assistant** | netbox.env | None | `/initial-setup` |
|
||||
@@ -402,21 +405,12 @@ PR_REVIEW_AUTO_SUBMIT=false
|
||||
|
||||
Once system-level config is set up, adding new projects is simple:
|
||||
|
||||
**Option 1: Use `/project-init` (faster)**
|
||||
```
|
||||
cd ~/projects/new-project
|
||||
/project-init
|
||||
/setup
|
||||
```
|
||||
|
||||
**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.
|
||||
The command auto-detects that system config exists and runs quick project setup.
|
||||
|
||||
---
|
||||
|
||||
@@ -424,12 +418,12 @@ Both approaches work. Use `/project-init` when you know the system is already co
|
||||
|
||||
### API Validation
|
||||
|
||||
When running `/initial-setup`, `/project-init`, or `/project-sync`, the commands:
|
||||
When running `/setup`, the command:
|
||||
|
||||
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)
|
||||
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.
|
||||
|
||||
@@ -439,7 +433,7 @@ 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 `/project-sync` to update."
|
||||
3. **Warns** if mismatch detected: "Repository location mismatch. Run `/setup --sync` to update."
|
||||
|
||||
This helps when you:
|
||||
- Move a repository to a different organization
|
||||
@@ -534,7 +528,7 @@ cat .env
|
||||
|
||||
3. **Never type tokens into AI chat**
|
||||
- Always edit config files directly in your editor
|
||||
- The `/initial-setup` wizard respects this
|
||||
- The `/setup` wizard respects this
|
||||
|
||||
4. **Rotate tokens periodically**
|
||||
- Every 6-12 months
|
||||
|
||||
@@ -73,25 +73,19 @@ cd $RUNTIME && ./scripts/setup.sh
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Verify Symlink Resolution
|
||||
## Step 4: Verify MCP Configuration
|
||||
|
||||
Plugins use symlinks to shared MCP servers. Verify they resolve correctly:
|
||||
Check `.mcp.json` at marketplace root is correctly configured:
|
||||
|
||||
```bash
|
||||
RUNTIME=~/.claude/plugins/marketplaces/leo-claude-mktplace
|
||||
|
||||
# Check symlinks exist and resolve
|
||||
readlink -f $RUNTIME/plugins/projman/mcp-servers/gitea
|
||||
readlink -f $RUNTIME/plugins/pr-review/mcp-servers/gitea
|
||||
readlink -f $RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox
|
||||
# Check .mcp.json exists and has valid content
|
||||
cat $RUNTIME/.mcp.json | jq '.mcpServers | keys'
|
||||
|
||||
# Should resolve to:
|
||||
# $RUNTIME/mcp-servers/gitea
|
||||
# $RUNTIME/mcp-servers/netbox
|
||||
# Should list: gitea, netbox, data-platform, viz-platform, contract-validator
|
||||
```
|
||||
|
||||
**If broken:** Symlinks are relative. If directory structure differs, they'll break.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Test MCP Server Startup
|
||||
@@ -165,10 +159,8 @@ echo -e "\n=== Virtual Environments ==="
|
||||
[ -f "$RUNTIME/mcp-servers/gitea/.venv/bin/python" ] && echo "Gitea venv: OK" || echo "Gitea venv: MISSING"
|
||||
[ -f "$RUNTIME/mcp-servers/netbox/.venv/bin/python" ] && echo "NetBox venv: OK" || echo "NetBox venv: MISSING"
|
||||
|
||||
echo -e "\n=== Symlinks ==="
|
||||
[ -L "$RUNTIME/plugins/projman/mcp-servers/gitea" ] && echo "projman->gitea: OK" || echo "projman->gitea: MISSING"
|
||||
[ -L "$RUNTIME/plugins/pr-review/mcp-servers/gitea" ] && echo "pr-review->gitea: OK" || echo "pr-review->gitea: MISSING"
|
||||
[ -L "$RUNTIME/plugins/cmdb-assistant/mcp-servers/netbox" ] && echo "cmdb-assistant->netbox: OK" || echo "cmdb-assistant->netbox: MISSING"
|
||||
echo -e "\n=== MCP Configuration ==="
|
||||
[ -f "$RUNTIME/.mcp.json" ] && echo ".mcp.json: OK" || echo ".mcp.json: MISSING"
|
||||
|
||||
echo -e "\n=== Config Files ==="
|
||||
[ -f ~/.config/claude/gitea.env ] && echo "gitea.env: OK" || echo "gitea.env: MISSING"
|
||||
@@ -182,7 +174,7 @@ echo -e "\n=== Config Files ==="
|
||||
| Issue | Symptom | Fix |
|
||||
|-------|---------|-----|
|
||||
| Missing venvs | "X MCP servers failed" | `cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh` |
|
||||
| Broken symlinks | MCP tools not available | Reinstall marketplace or manually recreate symlinks |
|
||||
| Missing .mcp.json | MCP tools not available | Check `.mcp.json` exists at marketplace root |
|
||||
| Wrong path edits | Changes don't take effect | Edit installed path or reinstall after source changes |
|
||||
| Missing credentials | MCP connection errors | Create `~/.config/claude/gitea.env` with API credentials |
|
||||
| Invalid hook events | Hooks don't fire | Use only valid event names (see Step 7) |
|
||||
@@ -287,8 +279,8 @@ Error: Could not find a suitable TLS CA certificate bundle, invalid path:
|
||||
|
||||
Use these commands for automated checking:
|
||||
|
||||
- `/debug-report` - Run full diagnostics, create issue if problems found
|
||||
- `/debug-review` - Investigate existing diagnostic issues and propose fixes
|
||||
- `/debug report` - Run full diagnostics, create issue if problems found
|
||||
- `/debug review` - Investigate existing diagnostic issues and propose fixes
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -162,7 +162,7 @@ If that doesn't work:
|
||||
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/gitea/.venv
|
||||
ls ~/.claude/plugins/marketplaces/leo-claude-mktplace/mcp-servers/netbox/.venv
|
||||
```
|
||||
3. If missing, the symlinks won't resolve. Run setup.sh as shown above.
|
||||
3. If missing, run setup.sh as shown above.
|
||||
4. Restart Claude Code session
|
||||
5. Check logs for specific errors
|
||||
|
||||
|
||||
Reference in New Issue
Block a user