leo-claude-mktplace/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

⛔ RULES - READ FIRST

Behavioral Rules

Rule	Summary
Check everything	Search cache (~/.claude/plugins/cache/), installed (~/.claude/plugins/marketplaces/), and source (~/claude-plugins-work/)
Believe the user	User knows their system. Investigate before disagreeing.
Verify before "done"	Run commands, show output, check all locations. "Done" = verified working.
Show what's asked	Don't interpret or summarize unless asked.

After Plugin Updates

Run ./scripts/verify-hooks.sh. If changes affect MCP servers or hooks, inform user to restart session. DO NOT clear cache mid-session - breaks loaded MCP tools.

Repository Rules

Rule	Details
File creation	Only in allowed paths. Use .scratch/ for temp work. Verify against docs/CANONICAL-PATHS.md
plugin.json location	Must be in .claude-plugin/ directory
Hooks	Use hooks/hooks.json (auto-discovered). Never inline in plugin.json
MCP servers	Shared at root with symlinks. Use MCP tools, never CLI (tea, gh)
Allowed root files	CLAUDE.md, README.md, LICENSE, CHANGELOG.md, .gitignore, .env.example

Valid hook events: PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Notification, Stop, SubagentStop, PreCompact

---

Project Overview

Repository: leo-claude-mktplace Version: 5.3.0 Status: Production Ready

A plugin marketplace for Claude Code containing:

Plugin	Description	Version
projman	Sprint planning and project management with Gitea integration	3.3.0
git-flow	Git workflow automation with smart commits and branch management	1.2.0
pr-review	Multi-agent PR review with confidence scoring	1.1.0
clarity-assist	Prompt optimization with ND-friendly accommodations	1.2.0
doc-guardian	Automatic documentation drift detection and synchronization	1.1.0
code-sentinel	Security scanning and code refactoring tools	1.0.0
claude-config-maintainer	CLAUDE.md optimization and maintenance	1.1.0
cmdb-assistant	NetBox CMDB integration for infrastructure management	1.2.0
data-platform	pandas, PostgreSQL, and dbt integration for data engineering	1.2.0
viz-platform	DMC validation, Plotly charts, and theming for dashboards	1.1.0
contract-validator	Cross-plugin compatibility validation and agent verification	1.2.0
project-hygiene	Post-task cleanup automation via hooks	0.1.0

Quick Start

# Validate marketplace compliance
./scripts/validate-marketplace.sh

# After updates
./scripts/post-update.sh   # Rebuild venvs, verify symlinks

Plugin Commands by Category

Category	Commands
Setup	/initial-setup, /project-init, /project-sync
Sprint	/sprint-plan, /sprint-start, /sprint-status, /sprint-close, /sprint-diagram
Quality	/review, /test-check, /test-gen
Versioning	/suggest-version
PR Review	/pr-review, /pr-summary, /pr-findings, /pr-diff
Docs	/doc-audit, /doc-sync, /changelog-gen, /doc-coverage, /stale-docs
Security	/security-scan, /refactor, /refactor-dry
Config	/config-analyze, /config-optimize, /config-diff, /config-lint
Data	/ingest, /profile, /schema, /explain, /lineage, /lineage-viz, /run, /dbt-test, /data-quality
Visualization	/component, /chart, /chart-export, /dashboard, /theme, /theme-new, /theme-css, /accessibility-check, /breakpoints
Validation	/validate-contracts, /check-agent, /list-interfaces, /dependency-graph
CMDB	/cmdb-search, /cmdb-device, /cmdb-ip, /cmdb-site, /cmdb-audit, /cmdb-register, /cmdb-sync, /cmdb-topology, /change-audit, /ip-conflicts
Debug	/debug-report, /debug-review

Repository Structure

leo-claude-mktplace/
├── .claude-plugin/
│   └── marketplace.json          # Marketplace manifest
├── mcp-servers/                  # SHARED MCP servers (v3.0.0+)
│   ├── gitea/                    # Gitea MCP (issues, PRs, wiki)
│   ├── netbox/                   # NetBox MCP (CMDB)
│   ├── data-platform/            # pandas, PostgreSQL, dbt
│   └── viz-platform/             # DMC validation, charts, themes
├── plugins/
│   ├── projman/                  # Sprint management
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .mcp.json
│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
│   │   ├── commands/             # 14 commands (incl. setup, debug, suggest-version)
│   │   ├── hooks/                # SessionStart: mismatch detection + sprint suggestions
│   │   ├── agents/               # 4 agents
│   │   └── skills/label-taxonomy/
│   ├── git-flow/                 # Git workflow automation
│   │   ├── .claude-plugin/plugin.json
│   │   ├── commands/             # 8 commands
│   │   └── agents/
│   ├── pr-review/                # Multi-agent PR review
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .mcp.json
│   │   ├── mcp-servers/gitea -> ../../../mcp-servers/gitea  # SYMLINK
│   │   ├── commands/             # 6 commands (incl. setup)
│   │   ├── hooks/                # SessionStart mismatch detection
│   │   └── agents/               # 5 agents
│   ├── clarity-assist/           # Prompt optimization
│   │   ├── .claude-plugin/plugin.json
│   │   ├── commands/             # 2 commands
│   │   └── agents/
│   ├── data-platform/            # Data engineering (NEW v4.0.0)
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .mcp.json
│   │   ├── mcp-servers/          # pandas, postgresql, dbt MCPs
│   │   ├── commands/             # 7 commands
│   │   ├── hooks/                # SessionStart PostgreSQL check
│   │   └── agents/               # 2 agents
│   ├── viz-platform/             # Visualization (NEW v4.0.0)
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .mcp.json
│   │   ├── mcp-servers/          # viz-platform MCP
│   │   ├── commands/             # 7 commands
│   │   ├── hooks/                # SessionStart DMC check
│   │   └── agents/               # 3 agents
│   ├── doc-guardian/             # Documentation drift detection
│   ├── code-sentinel/            # Security scanning & refactoring
│   ├── claude-config-maintainer/
│   ├── cmdb-assistant/
│   └── project-hygiene/
├── scripts/
│   ├── setup.sh, post-update.sh
│   ├── validate-marketplace.sh   # Marketplace compliance validation
│   ├── verify-hooks.sh           # Verify all hooks are command type
│   └── check-venv.sh             # Check MCP server venvs exist
└── docs/
    ├── CANONICAL-PATHS.md        # Single source of truth for paths
    └── CONFIGURATION.md          # Centralized configuration guide

Architecture

Four-Agent Model (projman)

Agent	Personality	Responsibilities
Planner	Thoughtful, methodical	Sprint planning, architecture analysis, issue creation, lesson search
Orchestrator	Concise, action-oriented	Sprint execution, parallel batching, Git operations, lesson capture
Executor	Implementation-focused	Code implementation, branch management, MR creation
Code Reviewer	Thorough, practical	Pre-close quality review, security scan, test verification

MCP Server Tools (Gitea)

Category	Tools
Issues	list_issues, get_issue, create_issue, update_issue, add_comment, aggregate_issues
Labels	get_labels, suggest_labels, create_label, create_label_smart
Milestones	list_milestones, get_milestone, create_milestone, update_milestone, delete_milestone
Dependencies	list_issue_dependencies, create_issue_dependency, remove_issue_dependency, get_execution_order
Wiki	list_wiki_pages, get_wiki_page, create_wiki_page, update_wiki_page, create_lesson, search_lessons
Pull Requests	list_pull_requests, get_pull_request, get_pr_diff, get_pr_comments, create_pr_review, add_pr_comment
Validation	validate_repo_org, get_branch_protection

Hybrid Configuration

Level	Location	Purpose
System	~/.config/claude/gitea.env	Credentials (GITEA_API_URL, GITEA_API_TOKEN)
Project	.env in project root	Repository specification (GITEA_ORG, GITEA_REPO)

Note: GITEA_ORG is at project level since different projects may belong to different organizations.

Branch-Aware Security

Branch Pattern	Mode	Capabilities
development, feat/*	Development	Full access
staging	Staging	Read-only code, can create issues
main, master	Production	Read-only, emergency only

Label Taxonomy

43 labels total: 27 organization + 16 repository

Organization: Agent/2, Complexity/3, Efforts/5, Priority/4, Risk/3, Source/4, Type/6 Repository: Component/9, Tech/7

Sync with /labels-sync command.

Lessons Learned System

Stored in Gitea Wiki under lessons-learned/sprints/.

Workflow:

1. Orchestrator captures at sprint close via MCP tools
2. Planner searches at sprint start using search_lessons
3. Tags enable cross-project discovery

Common Operations

Adding a New Plugin

1. Create plugins/{name}/.claude-plugin/plugin.json
2. Add entry to .claude-plugin/marketplace.json with category, tags, license
3. Create README.md and claude-md-integration.md
4. If using MCP server, create symlink: ln -s ../../../mcp-servers/{server} plugins/{name}/mcp-servers/{server}
5. Run ./scripts/validate-marketplace.sh
6. Update CHANGELOG.md

Adding a Command to projman

1. Create plugins/projman/commands/{name}.md
2. Update plugins/projman/README.md
3. Update marketplace description if significant

Validation

./scripts/validate-marketplace.sh  # Validates all manifests

Path Verification Protocol

Before creating any file:

1. Read docs/CANONICAL-PATHS.md
2. List all paths to be created/modified
3. Verify each against canonical paths
4. If not in canonical paths, STOP and ask

Documentation Index

Document	Purpose
docs/CANONICAL-PATHS.md	Single source of truth for paths
docs/COMMANDS-CHEATSHEET.md	All commands quick reference
docs/CONFIGURATION.md	Centralized setup guide
docs/DEBUGGING-CHECKLIST.md	Systematic troubleshooting guide
docs/UPDATING.md	Update guide for the marketplace
plugins/projman/CONFIGURATION.md	Projman quick reference (links to central)
plugins/projman/README.md	Projman full documentation

Installation Paths

Understanding where files live is critical for debugging:

Context	Path	Purpose
Source	~/claude-plugins-work/	Development - edit here
Installed	~/.claude/plugins/marketplaces/leo-claude-mktplace/	Runtime - Claude uses this
Cache	~/.claude/	Plugin metadata and settings

Key insight: Edits to source require reinstall/update to take effect at runtime.

Debugging & Troubleshooting

See docs/DEBUGGING-CHECKLIST.md for systematic troubleshooting.

Common Issues:

Symptom	Likely Cause	Fix
"X MCP servers failed"	Missing venv in installed path	cd ~/.claude/plugins/marketplaces/leo-claude-mktplace && ./scripts/setup.sh
MCP tools not available	Symlink broken or venv missing	Run /debug-report to diagnose
Changes not taking effect	Editing source, not installed	Reinstall plugin or edit installed path

Debug Commands:

• /debug-report - Run full diagnostics, create issue if needed
• /debug-review - Investigate and propose fixes

Versioning Workflow

This project follows SemVer and Keep a Changelog.

Version Locations (must stay in sync)

Location	Format	Example
Git tags	vX.Y.Z	v3.2.0
README.md title	# Leo Claude Marketplace - vX.Y.Z	v3.2.0
marketplace.json	"version": "X.Y.Z"	3.2.0
CHANGELOG.md	## [X.Y.Z] - YYYY-MM-DD	[3.2.0] - 2026-01-24

During Development

All changes go under [Unreleased] in CHANGELOG.md. Never create a versioned section until release time.

## [Unreleased]

### Added
- New feature description

### Fixed
- Bug fix description

Creating a Release

Use the release script to ensure consistency:

./scripts/release.sh 3.2.0

The script will:

1. Validate [Unreleased] section has content
2. Replace [Unreleased] with [3.2.0] - YYYY-MM-DD
3. Update README.md title
4. Update marketplace.json version
5. Commit and create git tag

SemVer Guidelines

Change Type	Version Bump	Example
Bug fixes only	PATCH (x.y.Z)	3.1.1 → 3.1.2
New features (backwards compatible)	MINOR (x.Y.0)	3.1.2 → 3.2.0
Breaking changes	MAJOR (X.0.0)	3.2.0 → 4.0.0

---

Last Updated: 2026-01-28