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.

NEVER USE CLI TOOLS FOR EXTERNAL SERVICES

• FORBIDDEN: gh, tea, curl to APIs, any CLI that talks to Gitea/GitHub/external services
• REQUIRED: Use MCP tools exclusively (mcp__plugin_projman_gitea__*, mcp__plugin_pr-review_gitea__*)
• NO EXCEPTIONS. Don't try CLI first. Don't fall back to CLI. MCP ONLY.

NEVER PUSH DIRECTLY TO PROTECTED BRANCHES

• FORBIDDEN: git push origin development, git push origin main, git push origin master
• REQUIRED: Create feature branch → push feature branch → create PR via MCP
• If you accidentally commit to a protected branch locally: git checkout -b fix/branch-name then reset the protected branch

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

⛔ MANDATORY: Before Any Code Change

Claude MUST show this checklist BEFORE editing any file:

1. Impact Search Results

Run and show output of:

grep -rn "PATTERN" --include="*.sh" --include="*.md" --include="*.json" --include="*.py" | grep -v ".git"

2. Files That Will Be Affected

Numbered list of every file to be modified, with the specific change for each.

3. Files Searched But Not Changed (and why)

Proof that related files were checked and determined unchanged.

4. Documentation That References This

List of docs that mention this feature/script/function.

User verifies this list before Claude proceeds. If Claude skips this, STOP IMMEDIATELY.

After Changes

Run the same grep and show results proving no references remain unaddressed.

---

⚠️ Development Context: We Build AND Use These Plugins

This is a self-referential project. We are:

1. BUILDING a plugin marketplace (source code in plugins/)
2. USING the installed marketplace to build it (dogfooding)

Plugins ACTIVELY USED in This Project

These plugins are installed and should be used during development:

Plugin	Used For
projman	Sprint planning, issue management, lessons learned
git-flow	Commits, branch management
pr-review	Pull request reviews
doc-guardian	Documentation drift detection
code-sentinel	Security scanning, refactoring
clarity-assist	Prompt clarification
claude-config-maintainer	CLAUDE.md optimization
contract-validator	Cross-plugin compatibility

Plugins NOT Used Here (Development Only)

These plugins exist in source but are NOT relevant to this project's workflow:

Plugin	Why Not Used
data-platform	For data engineering projects (pandas, PostgreSQL, dbt)
viz-platform	For dashboard projects (Dash, Plotly)
cmdb-assistant	For infrastructure projects (NetBox)

Do NOT suggest /ingest, /profile, /chart, /cmdb-* commands - they don't apply here.

Key Distinction

Context	Path	What To Do
Editing plugin source	~/claude-plugins-work/plugins/	Modify code, add features
Using installed plugins	~/.claude/plugins/marketplaces/	Run commands like /sprint-plan

When user says "run /sprint-plan", use the INSTALLED plugin. When user says "fix the sprint-plan command", edit the SOURCE code.

---

Project Overview

Repository: leo-claude-mktplace Version: 5.4.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.0.0
pr-review	Multi-agent PR review with confidence scoring	1.1.0
clarity-assist	Prompt optimization with ND-friendly accommodations	1.0.0
doc-guardian	Automatic documentation drift detection and synchronization	1.0.0
code-sentinel	Security scanning and code refactoring tools	1.0.1
claude-config-maintainer	CLAUDE.md optimization and maintenance	1.0.0
cmdb-assistant	NetBox CMDB integration for infrastructure management	1.2.0
data-platform	pandas, PostgreSQL, and dbt integration for data engineering	1.1.0
viz-platform	DMC validation, Plotly charts, and theming for dashboards	1.1.0
contract-validator	Cross-plugin compatibility validation and agent verification	1.1.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 - USE THESE in This Project

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
Validation	/validate-contracts, /check-agent, /list-interfaces, /dependency-graph
Debug	/debug-report, /debug-review

Plugin Commands - NOT RELEVANT to This Project

These commands are being developed but don't apply to this project's workflow:

Category	Commands	For Projects Using
Data	/ingest, /profile, /schema, /lineage, /dbt-test	pandas, PostgreSQL, dbt
Visualization	/component, /chart, /dashboard, /theme	Dash, Plotly dashboards
CMDB	/cmdb-search, /cmdb-device, /cmdb-sync	NetBox infrastructure

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 removed - now at marketplace root
│   │   ├── 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 removed - now at marketplace root
│   │   ├── 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 removed - now at marketplace root
│   │   ├── 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 removed - now at marketplace root
│   │   ├── 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.

Agent Model Configuration

Agents can specify preferred Claude models for cost/performance optimization:

Model	Use For	Agents
opus	Complex reasoning, security	planner, code-reviewer, security-reviewer
sonnet	Implementation, coordination	orchestrator, executor, most agents
haiku	Simple validation	component-check, agent-check

Configuration: Add model: opus|sonnet|haiku to agent frontmatter, or defaultModel to plugin.json. Inheritance: Agent → Plugin default → System default (sonnet)

See docs/MODEL-RECOMMENDATIONS.md for detailed guidance.

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-30