6 Commits

21 changed files with 93 additions and 370 deletions

109
CLAUDE.md
View File

@@ -1,44 +1,48 @@
# CLAUDE.md
This file provides guidance to Claude Code when working with code in this repository.
## ⛔ MANDATORY BEHAVIOR RULES - READ FIRST
## ⛔ RULES - READ FIRST
**These rules are NON-NEGOTIABLE. Violating them wastes the user's time and money.**
### Behavioral Rules
### 1. WHEN USER ASKS YOU TO CHECK SOMETHING - CHECK EVERYTHING
- Search ALL locations, not just where you think it is
- Check cache directories: `~/.claude/plugins/cache/`
- Check installed: `~/.claude/plugins/marketplaces/`
- Check source: `~/claude-plugins-work/`
- **NEVER say "no" or "that's not the issue" without exhaustive verification**
| 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. |
### 2. WHEN USER SAYS SOMETHING IS WRONG - BELIEVE THEM
- The user knows their system better than you
- Investigate thoroughly before disagreeing
- If user suspects cache, CHECK THE CACHE
- If user suspects a file, READ THE FILE
- **Your confidence is often wrong. User's instincts are often right.**
### After Plugin Updates
### 3. NEVER SAY "DONE" WITHOUT VERIFICATION
- Run the actual command/script to verify
- Show the output to the user
- Check ALL affected locations
- **"Done" means VERIFIED WORKING, not "I made changes"**
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.
### 4. SHOW EXACTLY WHAT USER ASKS FOR
- If user asks for messages, show the MESSAGES
- If user asks for code, show the CODE
- If user asks for output, show the OUTPUT
- **Don't interpret or summarize unless asked**
### 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.
### 5. AFTER PLUGIN UPDATES - VERIFY AND RESTART
### 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
**⚠️ DO NOT clear cache mid-session** - this breaks MCP tools that are already loaded.
### Repository Rules
1. Run `./scripts/verify-hooks.sh` to check hook types
2. If changes affect MCP servers or hooks, inform the user:
> "Plugin changes require a session restart to take effect. Please restart Claude Code."
3. Cache clearing is ONLY safe **before** starting a new session (not during)
| 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` |
See `docs/DEBUGGING-CHECKLIST.md` for details on cache timing.
**Valid hook events:** `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
**FAILURE TO FOLLOW THESE RULES = WASTED USER TIME = UNACCEPTABLE**
---
@@ -158,6 +162,40 @@ leo-claude-mktplace/
└── CONFIGURATION.md # Centralized configuration guide
```
## CRITICAL: Rules You MUST Follow
### File Operations
- **NEVER** create files in repository root unless listed in "Allowed Root Files"
- **NEVER** modify `.gitignore` without explicit permission
- **ALWAYS** use `.scratch/` for temporary/exploratory work
- **ALWAYS** verify paths against `docs/CANONICAL-PATHS.md` before creating files
### Plugin Development
- **plugin.json MUST be in `.claude-plugin/` directory** (not plugin root)
- **Every plugin MUST be listed in marketplace.json**
- **MCP servers are SHARED at root** with symlinks from plugins
- **MCP server venv path**: `${CLAUDE_PLUGIN_ROOT}/mcp-servers/{name}/.venv/bin/python`
- **CLI tools forbidden** - Use MCP tools exclusively (never `tea`, `gh`, etc.)
#### ⚠️ plugin.json Format Rules (CRITICAL)
- **Hooks in separate file** - Use `hooks/hooks.json` (auto-discovered), NOT inline in plugin.json
- **NEVER reference hooks** - Don't add `"hooks": "..."` field to plugin.json at all
- **Agents auto-discover** - NEVER add `"agents": ["./agents/"]` - .md files found automatically
- **Always validate** - Run `./scripts/validate-marketplace.sh` before committing
- **Working examples:** projman, pr-review, claude-config-maintainer all use `hooks/hooks.json`
- See lesson: `lessons/patterns/plugin-manifest-validation---hooks-and-agents-format-requirements`
### Hooks (Valid Events Only)
`PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Notification`, `Stop`, `SubagentStop`, `PreCompact`
**INVALID:** `task-completed`, `file-changed`, `git-commit-msg-needed`
### Allowed Root Files
`CLAUDE.md`, `README.md`, `LICENSE`, `CHANGELOG.md`, `.gitignore`, `.env.example`
### Allowed Root Directories
`.claude/`, `.claude-plugin/`, `.claude-plugins/`, `.scratch/`, `docs/`, `hooks/`, `mcp-servers/`, `plugins/`, `scripts/`
## Architecture
### Four-Agent Model (projman)
@@ -190,21 +228,6 @@ leo-claude-mktplace/
**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 |

View File

@@ -522,56 +522,6 @@ cat .env
---
## Agent Model Configuration
Agents can specify which Claude model to use for optimal cost/performance.
### Model Options
| Model | Use For | Cost |
|-------|---------|------|
| `opus` | Complex reasoning, security analysis | Highest |
| `sonnet` | Implementation, coordination (default) | Medium |
| `haiku` | Simple validation, quick checks | Lowest |
### Configuration Levels
**1. Agent-Level (highest priority)**
Add to agent frontmatter in `agents/*.md`:
```yaml
---
name: planner
description: Sprint planning agent
model: opus
---
```
**2. Plugin-Level (fallback)**
Add to `plugin.json`:
```json
{
"defaultModel": "sonnet"
}
```
**3. System Default**
If neither is specified, agents use `sonnet`.
### Inheritance Chain
```
Agent model → Plugin defaultModel → System default (sonnet)
```
See [Model Recommendations](MODEL-RECOMMENDATIONS.md) for detailed guidance on model selection by task type.
---
## Security Best Practices
1. **Never commit tokens**

View File

@@ -1,149 +0,0 @@
# Model Recommendations
Guidelines for selecting Claude models (opus, sonnet, haiku) for plugin agents.
---
## Model Overview
| Model | Best For | Cost | Speed |
|-------|----------|------|-------|
| **Opus** | Complex reasoning, architecture decisions, security analysis | Highest | Slower |
| **Sonnet** | Implementation, coordination, standard tasks | Medium | Balanced |
| **Haiku** | Simple validation, quick checks, status queries | Lowest | Fastest |
---
## Task-Type Recommendations
| Task Type | Model | Rationale |
|-----------|-------|-----------|
| Architecture decisions | Opus | Requires deep reasoning, trade-off analysis |
| Security analysis | Opus | Critical thinking, vulnerability pattern recognition |
| Code review (quality) | Opus | Thorough analysis, edge case detection |
| Sprint planning | Opus | Strategic thinking, dependency analysis |
| Complex data analysis | Opus | Multi-step reasoning, insight generation |
| Code implementation | Sonnet | Fast, capable code generation |
| Coordination/dispatch | Sonnet | Task management, status tracking |
| Data transformation | Sonnet | ETL operations, query building |
| Documentation | Sonnet | Clear writing, structure |
| Simple validation | Haiku | Fast prop checks, schema validation |
| Status checks | Haiku | Quick queries, cost-effective |
| Quick verification | Haiku | Simple pass/fail checks |
---
## Agent Model Assignments
### projman (Sprint Management)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `planner` | opus | Architecture decisions, issue structuring |
| `orchestrator` | sonnet | Coordination, parallel execution |
| `executor` | sonnet | Code implementation |
| `code-reviewer` | opus | Quality review, security analysis |
### pr-review (PR Analysis)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `coordinator` | sonnet | Task dispatch, result aggregation |
| `security-reviewer` | opus | Security vulnerability detection |
| `performance-analyst` | sonnet | Pattern recognition |
| `maintainability-auditor` | sonnet | Code quality checks |
| `test-validator` | sonnet | Test coverage analysis |
### code-sentinel (Security & Refactoring)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `security-reviewer` | opus | Security scanning |
| `refactor-advisor` | sonnet | Refactoring suggestions |
### data-platform (Data Engineering)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `data-analysis` | opus | Complex data insights |
| `data-ingestion` | sonnet | ETL operations |
### viz-platform (Visualization)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `component-check` | haiku | Simple prop validation |
| `layout-builder` | sonnet | UI construction |
| `theme-setup` | sonnet | Design configuration |
### contract-validator (Compatibility)
| Agent | Model | Rationale |
|-------|-------|-----------|
| `full-validation` | sonnet | Contract checking |
| `agent-check` | haiku | Quick verification |
---
## Configuration Schema
### Agent-Level (Frontmatter)
Add `model` field to agent YAML frontmatter:
```yaml
---
name: planner
description: Sprint planning agent
model: opus
---
```
**Valid values:** `opus`, `sonnet`, `haiku`
### Plugin-Level (plugin.json)
Add `defaultModel` for plugin-wide fallback:
```json
{
"name": "projman",
"version": "3.4.0",
"defaultModel": "sonnet"
}
```
---
## Inheritance Chain
Model selection follows this precedence:
```
1. Agent model field (highest priority)
↓ if not specified
2. Plugin defaultModel (plugin.json)
↓ if not specified
3. System default: sonnet
```
**Example:**
- Agent has `model: opus` → Uses opus
- Agent has no model, plugin has `defaultModel: sonnet` → Uses sonnet
- Neither specified → Uses sonnet (system default)
---
## Cost Optimization Tips
1. **Default to Sonnet** - Good balance for most tasks
2. **Reserve Opus** for critical decisions (security, architecture)
3. **Use Haiku** for validation and quick checks
4. **Batch simple tasks** - Use haiku for parallel validation
---
## See Also
- [Configuration Guide](CONFIGURATION.md) - Full configuration reference
- [Plugin Development](../README.md) - Adding new plugins

View File

@@ -1,8 +1,7 @@
{
"name": "code-sentinel",
"description": "Security scanning and code refactoring tools",
"version": "1.0.1",
"defaultModel": "sonnet",
"version": "1.0.0",
"author": {
"name": "Leo Miranda",
"email": "leobmiranda@gmail.com"

View File

@@ -1,7 +1,5 @@
---
name: security-reviewer
description: Security-focused code review agent
model: opus
---
# Security Reviewer Agent

View File

@@ -1,7 +1,6 @@
{
"name": "contract-validator",
"version": "1.1.0",
"defaultModel": "sonnet",
"version": "1.0.0",
"description": "Cross-plugin compatibility validation and Claude.md agent verification",
"author": {
"name": "Leo Miranda",

View File

@@ -1,9 +1,3 @@
---
name: agent-check
description: Agent definition validator for quick verification
model: haiku
---
# Agent Check Agent
You are an agent definition validator. Your role is to verify that a specific agent's tool references and data flow are valid.

View File

@@ -1,7 +1,6 @@
{
"name": "data-platform",
"version": "1.1.0",
"defaultModel": "sonnet",
"version": "1.0.0",
"description": "Data engineering tools with pandas, PostgreSQL/PostGIS, and dbt integration",
"author": {
"name": "Leo Miranda",

View File

@@ -1,9 +1,3 @@
---
name: data-analysis
description: Data analysis specialist for exploration and profiling
model: opus
---
# Data Analysis Agent
You are a data analysis specialist. Your role is to help users explore, profile, and understand their data.

View File

@@ -52,13 +52,7 @@ Then proceed with the sync.
- Single commit: `docs: sync documentation with code changes`
- Include summary of what was updated in commit body
5. **Clear Queue**
After successful sync, clear the queue file:
```bash
echo "# Doc Guardian Queue - cleared after sync on $(date +%Y-%m-%d)" > .doc-guardian-queue
```
6. **Output**
5. **Output**
```
## Documentation Sync Complete

View File

@@ -2,10 +2,6 @@
# doc-guardian notification hook
# Tracks documentation dependencies and queues updates
# This is a command hook - guaranteed not to block workflow
#
# IMPORTANT: Output is purely informational - uses passive language
# to avoid triggering Claude to seek user confirmation.
# Run /doc-sync to process the queue when ready.
# Read tool input from stdin (JSON with file_path)
INPUT=$(cat)
@@ -48,30 +44,6 @@ DEPENDENT_DOCS="${DOC_DEPS[$MODIFIED_TYPE]}"
# Queue file for tracking pending updates
QUEUE_FILE="${CLAUDE_PROJECT_ROOT:-.}/.doc-guardian-queue"
# Debounce: skip notification if same type was logged in last 5 seconds
# This prevents 4+ rapid notifications during batch edits
DEBOUNCE_SECONDS=5
if [ -f "$QUEUE_FILE" ]; then
LAST_ENTRY=$(tail -1 "$QUEUE_FILE" 2>/dev/null || true)
LAST_TYPE=$(echo "$LAST_ENTRY" | cut -d'|' -f2 | tr -d ' ')
LAST_TIME=$(echo "$LAST_ENTRY" | cut -d'|' -f1 | tr -d ' ')
if [ "$LAST_TYPE" = "$MODIFIED_TYPE" ] && [ -n "$LAST_TIME" ]; then
# Convert timestamps to seconds for comparison
LAST_EPOCH=$(date -d "$LAST_TIME" +%s 2>/dev/null || echo "0")
NOW_EPOCH=$(date +%s)
DIFF=$((NOW_EPOCH - LAST_EPOCH))
if [ "$DIFF" -lt "$DEBOUNCE_SECONDS" ]; then
# Still add to queue, but skip notification
{
echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
} >> "$QUEUE_FILE" 2>/dev/null || true
exit 0
fi
fi
fi
# Add to queue (create if doesn't exist, append if does)
{
echo "$(date +%Y-%m-%dT%H:%M:%S) | $MODIFIED_TYPE | $FILE_PATH | $DEPENDENT_DOCS"
@@ -80,8 +52,7 @@ fi
# Count pending updates
PENDING_COUNT=$(wc -l < "$QUEUE_FILE" 2>/dev/null | tr -d ' ' || echo "1")
# Output passive notification (no action implied)
# Uses "queued" instead of "update needed" to avoid triggering Claude to ask about it
echo "[doc-guardian] drift queued: $MODIFIED_TYPE$DEPENDENT_DOCS ($PENDING_COUNT total)"
# Output notification with specific docs that need updating
echo "[doc-guardian] $MODIFIED_TYPE changed → update needed: $DEPENDENT_DOCS (${PENDING_COUNT} pending)"
exit 0

View File

@@ -1,16 +1,19 @@
{
"hooks": [
{
"event": "PreToolUse",
"matcher": "Bash",
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
},
{
"event": "PreToolUse",
"matcher": "Bash",
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
}
]
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/branch-check.sh"
},
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/commit-msg-check.sh"
}
]
}
]
}
}

View File

@@ -1,7 +1,6 @@
{
"name": "pr-review",
"version": "1.1.0",
"defaultModel": "sonnet",
"version": "1.0.0",
"description": "Multi-agent pull request review with confidence scoring and actionable feedback",
"author": {
"name": "Leo Miranda",

View File

@@ -1,9 +1,3 @@
---
name: security-reviewer
description: Security-focused code reviewer for PR analysis
model: opus
---
# Security Reviewer Agent
## Visual Output Requirements

View File

@@ -1,7 +1,6 @@
{
"name": "projman",
"version": "3.3.0",
"defaultModel": "sonnet",
"version": "3.2.0",
"description": "Sprint planning and project management with Gitea integration",
"author": {
"name": "Leo Miranda",

View File

@@ -1,7 +1,6 @@
---
name: code-reviewer
description: Specialized agent for pre-sprint code quality review
model: opus
---
# Code Reviewer Agent

View File

@@ -1,7 +1,6 @@
---
name: planner
description: Sprint planning agent - thoughtful architecture analysis and issue creation
model: opus
---
# Sprint Planner Agent

View File

@@ -385,13 +385,6 @@ git push -u origin fix/issue-[NUMBER]-[brief-description]
git checkout development
```
**⚠️ IMPORTANT: Issue will NOT auto-close**
PRs merged to `development` do NOT trigger Gitea's auto-close feature.
Auto-close only works when merging to the default branch (`main`).
You MUST manually close the issue in Step 15 after the PR is merged.
5. Add comment to original issue:
```
mcp__plugin_projman_gitea__add_comment(
@@ -424,14 +417,9 @@ Next Steps:
**This step runs AFTER the user has verified the fix works.**
**⚠️ MANDATORY: You MUST manually close the issue.**
PRs merged to `development` do NOT auto-close issues (Gitea only auto-closes
on merges to the default branch `main`). Always close manually after merge.
When user returns and confirms the fix is working:
**1. Close the issue (REQUIRED - won't auto-close):**
**1. Close the issue:**
```
mcp__plugin_projman_gitea__update_issue(

View File

@@ -81,29 +81,6 @@ if [[ -f ".env" ]]; then
fi
fi
# ============================================================================
# Check version consistency across files (early drift detection)
# ============================================================================
# Versions must stay in sync across: README.md, marketplace.json, CHANGELOG.md
# Drift here causes confusion and release issues
if [[ -f "README.md" && -f ".claude-plugin/marketplace.json" && -f "CHANGELOG.md" ]]; then
VERSION_README=$(grep -oE "^# .* - v[0-9]+\.[0-9]+\.[0-9]+" README.md 2>/dev/null | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
# Extract metadata.version specifically (appears after "metadata" in marketplace.json)
VERSION_MARKETPLACE=$(sed -n '/"metadata"/,/}/p' .claude-plugin/marketplace.json 2>/dev/null | grep -oE '"version"[[:space:]]*:[[:space:]]*"[0-9]+\.[0-9]+\.[0-9]+"' | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
VERSION_CHANGELOG=$(grep -oE "^## \[[0-9]+\.[0-9]+\.[0-9]+\]" CHANGELOG.md 2>/dev/null | head -1 | grep -oE "[0-9]+\.[0-9]+\.[0-9]+" || echo "")
if [[ -n "$VERSION_README" && -n "$VERSION_MARKETPLACE" && -n "$VERSION_CHANGELOG" ]]; then
if [[ "$VERSION_README" != "$VERSION_MARKETPLACE" ]] || [[ "$VERSION_README" != "$VERSION_CHANGELOG" ]]; then
echo "$PREFIX Version mismatch detected:"
echo "$PREFIX README.md: v$VERSION_README"
echo "$PREFIX marketplace.json: v$VERSION_MARKETPLACE"
echo "$PREFIX CHANGELOG.md: v$VERSION_CHANGELOG"
echo "$PREFIX Run /suggest-version to analyze and fix"
fi
fi
fi
# Check for CHANGELOG.md [Unreleased] content (version management)
if [[ -f "CHANGELOG.md" ]]; then
# Check if there's content under [Unreleased] that hasn't been released

View File

@@ -1,7 +1,6 @@
{
"name": "viz-platform",
"version": "1.1.0",
"defaultModel": "sonnet",
"version": "1.0.0",
"description": "Visualization tools with Dash Mantine Components validation, Plotly charts, and theming",
"author": {
"name": "Leo Miranda",

View File

@@ -1,9 +1,3 @@
---
name: component-check
description: DMC component validation specialist
model: haiku
---
# Component Check Agent
You are a strict component validation specialist. Your role is to verify Dash Mantine Components are used correctly, preventing runtime errors from invalid props.