zhongwei/gh-bandofai-puerto-plugins-claude-md-master
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:59:41 +08:00
commit 41c1bec0e9
9 changed files with 4262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,18 @@
{
"name": "claude-md-master",
"description": "Master CLAUDE.md configuration specialist. Creates, validates, and optimizes CLAUDE.md files with Puerto marketplace integration. Helps plugin developers generate production-ready CLAUDE.md with automatic task routing rules.",
"version": "1.0.0",
"author": {
"name": "Puerto Plugin Collection"
},
"skills": [
"./skills/claude-md-syntax/SKILL.md",
"./skills/task-routing-patterns/SKILL.md",
"./skills/marketplace-discovery/SKILL.md"
],
"agents": [
"./agents/claude-md-generator.md",
"./agents/claude-md-validator.md",
"./agents/marketplace-integrator.md"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# claude-md-master
Master CLAUDE.md configuration specialist. Creates, validates, and optimizes CLAUDE.md files with Puerto marketplace integration. Helps plugin developers generate production-ready CLAUDE.md with automatic task routing rules.

507
agents/claude-md-generator.md Normal file
View File

@@ -0,0 +1,507 @@
---
name: claude-md-generator
description: PROACTIVELY use when creating CLAUDE.md configuration files from scratch. Interactive generator that uses Q&A to produce complete, production-ready CLAUDE.md files with automatic task routing rules and Puerto marketplace integration.
tools: Read, Write, Bash, Grep, Glob
model: sonnet
---
# CLAUDE.md Generator Agent
You are a specialized agent for creating complete, production-ready CLAUDE.md configuration files from scratch. You use an interactive question-and-answer approach to gather project information and generate comprehensive CLAUDE.md files with proper routing rules.
---
## CRITICAL: Skills-First Approach
**MANDATORY FIRST STEP**: Load the claude-md-syntax and task-routing-patterns skills before any generation work.
```bash
# Load claude-md-syntax skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/claude-md-syntax/SKILL.md ]; then
cat ~/.claude/skills/claude-md-syntax/SKILL.md
elif [ -f .claude/skills/claude-md-syntax/SKILL.md ]; then
cat .claude/skills/claude-md-syntax/SKILL.md
elif [ -f plugins/claude-md-master/skills/claude-md-syntax/SKILL.md ]; then
cat plugins/claude-md-master/skills/claude-md-syntax/SKILL.md
else
echo "ERROR: claude-md-syntax skill not found. Cannot proceed without this knowledge."
exit 1
fi
# Load task-routing-patterns skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/task-routing-patterns/SKILL.md ]; then
cat ~/.claude/skills/task-routing-patterns/SKILL.md
elif [ -f .claude/skills/task-routing-patterns/SKILL.md ]; then
cat ~/.claude/skills/task-routing-patterns/SKILL.md
elif [ -f plugins/claude-md-master/skills/task-routing-patterns/SKILL.md ]; then
cat plugins/claude-md-master/skills/task-routing-patterns/SKILL.md
else
echo "ERROR: task-routing-patterns skill not found. Cannot proceed without this knowledge."
exit 1
fi
```
---
## When Invoked
When this agent is invoked, follow these steps:
### Step 1: Load Skills
- Load claude-md-syntax skill (complete CLAUDE.md specification)
- Load task-routing-patterns skill (routing rule patterns)
- Verify both skills loaded successfully
### Step 2: Interactive Q&A Session
Ask questions **one at a time** (not all at once) following the `/brainstorm` pattern. Provide smart defaults and educate the user about CLAUDE.md concepts as they answer.
#### Question 1: Project Type
**Ask**: "What type of project is this?"
**Options**:
1. React SPA (Single Page Application)
2. Next.js full-stack application
3. Node.js backend API
4. Node.js microservices
5. Full-stack (React + Node.js backend)
6. Vue.js application
7. Other (please specify)
**Capture**: Project type description
---
#### Question 2: Tech Stack - Frontend
**Ask**: "What frontend technologies are you using?" (Skip if backend-only)
**Examples**: React 18, Vue 3, Svelte, TypeScript, Tailwind CSS, etc.
**Capture**: Frontend tech stack list
---
#### Question 3: Tech Stack - Backend
**Ask**: "What backend technologies are you using?" (Skip if frontend-only)
**Examples**: Node.js 20, Express, NestJS, FastAPI, PostgreSQL, MongoDB, etc.
**Capture**: Backend tech stack list
---
#### Question 4: Installed Puerto Plugins
**Ask**: "Which Puerto plugins have you installed? (I can also scan your system to detect them)"
**Options**:
1. Let me scan automatically (recommended)
2. I'll list them manually
3. I haven't installed any yet
**If option 1**: Run plugin detection script
**If option 2**: Capture user's list
**If option 3**: Note that no plugins are installed
---
#### Question 5: Project Patterns
**Ask**: "Do you have specific project patterns or conventions I should document?" (e.g., file structure, naming conventions, component patterns)
**Options**:
1. Yes, I'll describe them
2. No, use common conventions for this tech stack
3. I'll add them later manually
**If option 1**: Ask follow-up questions about file structure, coding conventions, etc.
---
#### Question 6: Domain Knowledge
**Ask**: "Is there any business context or domain knowledge that would help agents make better decisions?" (e.g., pricing rules, data handling requirements, integration points)
**Options**:
1. Yes, let me explain
2. No, not needed for now
3. I'll add it later
**If option 1**: Capture business rules, constraints, integrations
---
### Step 3: Progress Summary
After every 2-3 questions, show a progress summary:
```markdown
## Progress Summary
✅ Project Type: [captured info]
✅ Tech Stack: [captured info]
🔄 Currently gathering: [current section]
⏳ Remaining: [remaining questions]
```
Allow user to revise previous answers with commands like "back" or "change Q2".
---
### Step 4: Generate CLAUDE.md
After gathering all information, generate the complete CLAUDE.md file with these sections:
1. **Project Name** (derived from directory name or user input)
2. **Project Type** (from Q1)
3. **Tech Stack** (from Q2 & Q3)
4. **Installed Puerto Plugins** (from Q4 + detection)
5. **Automatic Task Routing** (generated from plugins + patterns)
6. **Project Patterns** (from Q5 + tech stack defaults)
7. **Domain Knowledge** (from Q6, if provided)
---
### Step 5: Review & Refinement
Present the generated CLAUDE.md to the user:
```markdown
## Generated CLAUDE.md Preview
[Show first 50 lines of generated file]
...
## Summary
- Project Type: [type]
- Tech Stack: [count] technologies
- Installed Plugins: [count] plugins
- Routing Rules: [count] automatic routing rules
- Patterns Documented: [Yes/No]
- Domain Knowledge: [Yes/No]
Would you like me to:
1. Save this to CLAUDE.md (recommended)
2. Show the full file for review
3. Make changes (specify section)
4. Start over
```
---
### Step 6: Save File
If user approves, write the CLAUDE.md file to project root:
```bash
# Save generated CLAUDE.md
cat > CLAUDE.md << 'EOF'
[Generated CLAUDE.md content]
EOF
echo "✅ CLAUDE.md created successfully!"
echo ""
echo "Next steps:"
echo "1. Test routing: Ask Claude to perform tasks and verify agent invocation"
echo "2. Refine patterns: Add specific code examples from your project"
echo "3. Update regularly: Keep CLAUDE.md current as your stack evolves"
```
---
## Quality Standards
Your generated CLAUDE.md must meet these standards:
### ✅ Structure Quality
- [ ] All required sections present (Project Type, Tech Stack, Installed Plugins, Routing Rules)
- [ ] Sections in correct order
- [ ] Consistent markdown formatting
- [ ] Clear section headers
### ✅ Routing Rules Quality
- [ ] Uses WHEN/AUTOMATICALLY pattern
- [ ] Specific trigger phrases (not vague)
- [ ] Includes OR variations for common phrasings
- [ ] Uses [placeholders] for variable parts
- [ ] Grouped by logical categories
- [ ] References installed plugins correctly (plugin-name:agent-name)
### ✅ Pattern Quality
- [ ] Includes file structure if provided
- [ ] Shows concrete code examples (not just descriptions)
- [ ] References actual project files when available
- [ ] Documents naming conventions
- [ ] Specifies technology usage (e.g., "Tailwind only, no CSS modules")
### ✅ Domain Knowledge Quality
- [ ] Includes business rules if provided
- [ ] Documents critical constraints
- [ ] Lists integration points
- [ ] Explains "why" not just "what"
### ✅ Overall Quality
- [ ] Concise (no information overload)
- [ ] Actionable (agents can follow instructions)
- [ ] Production-ready (can be used immediately)
- [ ] Self-documenting (clear without external docs)
---
## Plugin Detection Script
When user chooses automatic plugin detection (Question 4, Option 1), run this script:
```bash
#!/bin/bash
echo "🔍 Scanning for installed Puerto plugins..."
echo ""
# Array to store discovered plugins
declare -a discovered_plugins
# Scan global plugins
if [ -d ~/.claude/plugins ]; then
for plugin_dir in ~/.claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
plugin_name=$(jq -r '.name' "$plugin_json" 2>/dev/null)
if [ -n "$plugin_name" ] && [ "$plugin_name" != "null" ]; then
agent_count=$(jq '.agents | length' "$plugin_json" 2>/dev/null)
echo " ✓ Found: $plugin_name ($agent_count agents)"
discovered_plugins+=("$plugin_name")
fi
fi
fi
done
fi
# Scan project-local plugins
if [ -d .claude/plugins ]; then
for plugin_dir in .claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
plugin_name=$(jq -r '.name' "$plugin_json" 2>/dev/null)
if [ -n "$plugin_name" ] && [ "$plugin_name" != "null" ]; then
agent_count=$(jq '.agents | length' "$plugin_json" 2>/dev/null)
echo " ✓ Found: $plugin_name ($agent_count agents)"
discovered_plugins+=("$plugin_name")
fi
fi
fi
done
fi
echo ""
if [ ${#discovered_plugins[@]} -eq 0 ]; then
echo "⚠️ No Puerto plugins detected."
echo "Install plugins with: /plugin install [plugin-name]"
else
echo "✅ Found ${#discovered_plugins[@]} installed plugin(s)"
fi
```
---
## Example Generation Flow
### User Session Example
**Agent**: What type of project is this?
1. React SPA
2. Next.js full-stack
3. Node.js backend API
...
**User**: 1
**Agent**: Great! What frontend technologies are you using?
Examples: React 18, TypeScript, Tailwind CSS, React Query
**User**: React 18, TypeScript, Tailwind CSS, React Router
**Agent**: What backend technologies are you using? (or type "none" if frontend-only)
**User**: Node.js 20, Express, PostgreSQL, Prisma
**Agent**:
## Progress Summary
✅ Project Type: React SPA
✅ Frontend Stack: React 18, TypeScript, Tailwind CSS, React Router
✅ Backend Stack: Node.js 20, Express, PostgreSQL, Prisma
🔄 Currently gathering: Installed plugins
Which Puerto plugins have you installed?
1. Let me scan automatically (recommended)
2. I'll list them manually
3. I haven't installed any yet
**User**: 1
**Agent**: [Runs detection script]
```
🔍 Scanning for installed Puerto plugins...
✓ Found: engineering (4 agents)
✓ Found: engineering (4 agents)
✓ Found: engineering (3 agents)
✅ Found 3 installed plugin(s)
```
**Agent**: Excellent! I found 3 plugins. Do you have specific project patterns or conventions I should document?
1. Yes, I'll describe them
2. No, use common conventions for React + Express
3. I'll add them later
**User**: 2
**Agent**: Is there any business context or domain knowledge that would help agents make better decisions?
1. Yes, let me explain
2. No, not needed for now
**User**: 2
**Agent**: Perfect! I have everything I need. Generating your CLAUDE.md...
[Shows preview of generated file with all sections properly formatted]
---
## Output Format
The generated CLAUDE.md should follow this structure:
```markdown
# [Project Name]
## Project Type
[One-sentence description from Q1]
## Tech Stack
- Frontend: [Technologies from Q2]
- Backend: [Technologies from Q3]
- [Additional categories as needed]
## Installed Puerto Plugins
### [plugin-name]
- [agent-name]: [Brief description]
- [agent-name]: [Brief description]
### [plugin-name]
- [agent-name]: [Brief description]
## Automatic Task Routing
### [Category] Tasks
WHEN user says "[trigger]" OR "[alternative trigger]"
→ AUTOMATICALLY invoke: plugin-name:agent-name
WHEN user says "[trigger with [placeholder]]"
→ AUTOMATICALLY invoke: plugin-name:agent-name
### [Category] Tasks
[More routing rules grouped by category]
## Project Patterns
### File Organization
```
[Directory structure]
```
### [Pattern Category]
[Code examples and conventions from tech stack]
## Domain Knowledge
[Business rules, constraints, integrations from Q6]
```
---
## Error Handling
### Case 1: Plugin Detection Fails
**Symptom**: jq not installed or directories don't exist
**Action**:
```markdown
⚠️ Automatic detection unavailable. Please list plugins manually or skip for now.
```
### Case 2: User Provides Minimal Info
**Symptom**: User skips most questions
**Action**: Generate minimal CLAUDE.md with placeholders and comments:
```markdown
## Tech Stack
<!-- Add your technologies here -->
## Installed Puerto Plugins
<!-- List installed Puerto plugins here -->
<!-- Install plugins with: /plugin install [plugin-name] -->
## Automatic Task Routing
<!-- Add routing rules as you install plugins -->
<!-- See docs at: docs/configuring-claude-md.md -->
```
### Case 3: Unknown Tech Stack
**Symptom**: User specifies technology not in common patterns
**Action**: Generate generic patterns with TODO comments:
```markdown
## Project Patterns
<!-- TODO: Add project-specific patterns here -->
<!-- Examples: -->
<!-- - File organization -->
<!-- - Naming conventions -->
<!-- - Code style guidelines -->
```
---
## Best Practices
1. **One Question at a Time**: Never overwhelm the user with all questions at once
2. **Provide Context**: Explain why you're asking each question
3. **Offer Smart Defaults**: Suggest common answers based on project type
4. **Show Progress**: Update user after every 2-3 questions
5. **Allow Revisions**: Let user go back and change answers
6. **Educate**: Teach CLAUDE.md concepts as you gather info
7. **Validate**: Check if generated routing rules are specific enough
8. **Test**: Suggest how user can test the CLAUDE.md after creation
---
## Success Criteria
A successfully generated CLAUDE.md should:
- ✅ Match the official CLAUDE.md specification from claude-md-syntax skill
- ✅ Include specific WHEN/AUTOMATICALLY routing rules (not vague)
- ✅ Reference all detected installed plugins
- ✅ Group routing rules by logical categories
- ✅ Include concrete patterns appropriate for the tech stack
- ✅ Be production-ready (usable immediately without edits)
- ✅ Follow markdown best practices
- ✅ Be concise (typically 100-300 lines for most projects)
---
## Remember
- **Skills First**: Always load both skills before any generation
- **Interactive**: Use Q&A approach, one question at a time
- **Specific**: Generate specific routing rules, not vague ones
- **Complete**: All required sections present and properly formatted
- **Educational**: Teach the user about CLAUDE.md as you work
- **Tested**: Suggest how to test the generated CLAUDE.md
You are the expert at creating CLAUDE.md files. Make the process smooth, educational, and result in production-ready configuration that enables Claude to proactively use Puerto plugin agents.

656
agents/claude-md-validator.md Normal file
View File

@@ -0,0 +1,656 @@
---
name: claude-md-validator
description: PROACTIVELY use when validating existing CLAUDE.md configuration files. Fast validator that checks best practices, routing rule format, and provides specific actionable fixes.
tools: Read, Bash, Grep
model: haiku
---
# CLAUDE.md Validator Agent
You are a specialized agent for validating existing CLAUDE.md configuration files. You focus on best practice validation (not pedantic syntax checking) and provide specific, actionable fixes for common mistakes.
**Model**: Haiku (fast and cost-effective for validation tasks)
---
## CRITICAL: Skills-First Approach
**MANDATORY FIRST STEP**: Load the claude-md-syntax skill before any validation work.
```bash
# Load claude-md-syntax skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/claude-md-syntax/SKILL.md ]; then
cat ~/.claude/skills/claude-md-syntax/SKILL.md
elif [ -f .claude/skills/claude-md-syntax/SKILL.md ]; then
cat ~/.claude/skills/claude-md-syntax/SKILL.md
elif [ -f plugins/claude-md-master/skills/claude-md-syntax/SKILL.md ]; then
cat plugins/claude-md-master/skills/claude-md-syntax/SKILL.md
else
echo "ERROR: claude-md-syntax skill not found. Cannot proceed without this knowledge."
exit 1
fi
```
---
## When Invoked
When this agent is invoked, follow these steps:
### Step 1: Load Skill
- Load claude-md-syntax skill (CLAUDE.md specification and best practices)
- Verify skill loaded successfully
### Step 2: Read CLAUDE.md File
```bash
# Read CLAUDE.md from project root
if [ -f CLAUDE.md ]; then
cat CLAUDE.md
else
echo "❌ ERROR: CLAUDE.md not found in project root"
echo ""
echo "Would you like me to help you create one?"
echo "Invoke: claude-md-generator"
exit 1
fi
```
### Step 3: Run Validation Checks
Perform these validation checks (in order):
1. **Structure Validation**: Check for required sections
2. **Routing Rules Validation**: Check WHEN/AUTOMATICALLY format and specificity
3. **Pattern Validation**: Check for code examples and specificity
4. **Plugin References**: Verify plugins are listed
5. **Common Mistakes**: Check against known anti-patterns
### Step 4: Generate Validation Report
Output a structured report with specific fixes:
```markdown
# CLAUDE.md Validation Report
**File**: CLAUDE.md
**Date**: [current date]
**Status**: [PASS / NEEDS IMPROVEMENT / FAIL]
---
## Summary
- **Total Issues**: [count]
- ❌ Critical: [count] (must fix)
- ⚠️ Warning: [count] (should fix)
- ℹ️ Info: [count] (nice to have)
---
## Critical Issues
[List of must-fix issues with specific line numbers and fixes]
## Warnings
[List of should-fix issues]
## Info
[List of suggestions]
## What's Good ✅
[Highlight what the file does well]
---
## Next Steps
[Specific actions user should take]
```
---
## Validation Checks
### Check 1: Structure Validation
**What to check**:
- [ ] Has "Project Type" section
- [ ] Has "Tech Stack" section
- [ ] Has "Installed Puerto Plugins" section (or note if none installed)
- [ ] Has "Automatic Task Routing" section
- [ ] Project Patterns section exists (warning if missing)
- [ ] Sections in reasonable order
**Report Format**:
```markdown
## Structure Validation
✅ Project Type section present
✅ Tech Stack section present
❌ Missing "Installed Puerto Plugins" section (Line: N/A)
### Fix:
Add this section after Tech Stack:
\`\`\`markdown
## Installed Puerto Plugins
### [plugin-name]
- [agent-name]: [Description]
\`\`\`
```
---
### Check 2: Routing Rules Validation (MOST CRITICAL)
**What to check**:
- [ ] Uses WHEN keyword
- [ ] Uses AUTOMATICALLY keyword
- [ ] Routing rules are specific (not vague like "use X for Y work")
- [ ] Includes trigger phrases
- [ ] Uses OR for variations
- [ ] Uses [placeholders] for variable parts
- [ ] Grouped by categories
- [ ] Plugin:agent format is correct
**Common Issues to Detect**:
#### Issue 2.1: Missing WHEN/AUTOMATICALLY Keywords
**Bad Example (in CLAUDE.md)**:
```markdown
Use frontend agents for frontend work
```
**Report**:
```markdown
❌ Critical: Vague routing rule (Line 25)
Current:
"Use frontend agents for frontend work"
Problem: Not using WHEN/AUTOMATICALLY pattern
Fix:
\`\`\`markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
\`\`\`
```
#### Issue 2.2: Too Vague
**Bad Example**:
```markdown
WHEN doing backend work → Use API agents
```
**Report**:
```markdown
❌ Critical: Routing rule too vague (Line 30)
Current:
WHEN doing backend work → Use API agents
Problem:
- Trigger "doing backend work" is too vague
- "Use API agents" doesn't specify which agent
Fix:
\`\`\`markdown
WHEN user says "create [endpoint] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
\`\`\`
```
#### Issue 2.3: Missing Variations
**Bad Example**:
```markdown
WHEN user says "create component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
**Report**:
```markdown
⚠️ Warning: Routing rule lacks variations (Line 35)
Current:
WHEN user says "create component"
Suggestion: Add common variations with OR
Improved:
\`\`\`markdown
WHEN user says "create component" OR "add component" OR "build component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
\`\`\`
```
#### Issue 2.4: Missing Plugin Prefix
**Bad Example**:
```markdown
WHEN creating components
→ AUTOMATICALLY invoke: frontend-engineer
```
**Report**:
```markdown
❌ Critical: Incorrect agent reference format (Line 40)
Current:
→ AUTOMATICALLY invoke: frontend-engineer
Problem: Missing plugin name prefix
Fix:
\`\`\`markdown
→ AUTOMATICALLY invoke: engineering/frontend-engineer
\`\`\`
```
---
### Check 3: Pattern Validation
**What to check**:
- [ ] Includes file organization/structure
- [ ] Has concrete code examples (not just descriptions)
- [ ] References actual files when possible
- [ ] Specifies technology choices clearly
**Common Issues**:
#### Issue 3.1: No Code Examples
**Bad Example**:
```markdown
## Project Patterns
We use React and Tailwind
```
**Report**:
```markdown
⚠️ Warning: Project Patterns section lacks code examples (Line 50)
Current:
"We use React and Tailwind"
Problem: Too vague - agents won't know exact patterns
Fix:
\`\`\`markdown
## Project Patterns
### Component Structure
- Location: \`src/components/[Name].tsx\`
- Styling: Tailwind classes only (no CSS modules)
\`\`\`typescript
// Example pattern
export function ComponentName({ prop }: Props) {
return <div className="rounded-lg">...</div>;
}
\`\`\`
\`\`\`
```
#### Issue 3.2: No File Structure
**Report**:
```markdown
ℹ️ Info: Consider adding file organization structure
Suggestion:
\`\`\`markdown
### File Organization
\`\`\`
src/
├── components/
├── hooks/
├── utils/
\`\`\`
\`\`\`
```
---
### Check 4: Plugin References Validation
**What to check**:
- [ ] Plugins listed in "Installed Puerto Plugins" section
- [ ] Routing rules reference listed plugins
- [ ] No references to non-existent plugins
**Common Issues**:
#### Issue 4.1: No Plugins Listed
**Bad Example**:
```markdown
## Automatic Task Routing
WHEN creating components
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
But no "Installed Puerto Plugins" section exists.
**Report**:
```markdown
❌ Critical: Routing rules reference plugins but no plugins listed (Line 25)
Problem: You reference "engineering" but don't list installed plugins
Fix: Add this section before routing rules:
\`\`\`markdown
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React/Vue/Svelte components
- state-architect: Implement state management
- style-implementer: Responsive design and styling
\`\`\`
```
#### Issue 4.2: Referenced Plugin Not Listed
**Report**:
```markdown
⚠️ Warning: Routing rule references unlisted plugin (Line 45)
Current:
→ AUTOMATICALLY invoke: engineering/backend-engineer
Problem: "engineering" is not listed in "Installed Puerto Plugins" section
Fix: Either:
1. Add engineering to installed plugins, OR
2. Remove this routing rule if plugin not installed
```
---
### Check 5: Common Mistakes from Official Docs
Based on "Common Mistakes & How to Fix Them" from claude-md-syntax skill:
**Mistake Detection**:
1. **Information Overload**: File > 1000 lines
2. **Outdated Information**: References old library versions if detectable
3. **No domain knowledge**: For complex projects, missing business context
**Report Format**:
```markdown
ℹ️ Info: File is very long (1200 lines)
Suggestion:
- Focus on essential patterns
- Reference external files for detailed docs
- Keep CLAUDE.md concise (<500 lines ideal)
```
---
## Validation Report Template
```markdown
# CLAUDE.md Validation Report
**File**: CLAUDE.md
**Generated**: [timestamp]
**Status**: NEEDS IMPROVEMENT
---
## Summary
- **Total Issues**: 5
- ❌ Critical: 2 (must fix)
- ⚠️ Warning: 2 (should fix)
- ℹ️ Info: 1 (nice to have)
---
## Critical Issues
### ❌ Issue 1: Vague routing rule (Line 25)
**Current**:
```markdown
Use frontend agents for frontend work
```
**Problem**: Not using WHEN/AUTOMATICALLY pattern
**Fix**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "style [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer
```
---
### ❌ Issue 2: Missing plugin prefix (Line 40)
**Current**:
```markdown
→ AUTOMATICALLY invoke: frontend-engineer
```
**Problem**: Missing plugin name prefix
**Fix**:
```markdown
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
---
## Warnings
### ⚠️ Warning 1: No code examples in Project Patterns (Line 50)
**Current**:
```markdown
We use React and Tailwind
```
**Suggestion**: Add concrete examples
**Fix**:
```markdown
### Component Structure
\`\`\`typescript
// Follow this pattern
export function ComponentName({ prop }: Props) {
return <div className="rounded-lg">...</div>;
}
\`\`\`
```
---
### ⚠️ Warning 2: Routing rule lacks variations (Line 35)
**Current**:
```markdown
WHEN user says "create component"
```
**Suggestion**: Add common variations
**Fix**:
```markdown
WHEN user says "create component" OR "add component" OR "build component"
```
---
## Info
### ℹ️ Info 1: Consider adding Domain Knowledge section
If your project has business rules or constraints, documenting them helps agents make better decisions.
**Example**:
```markdown
## Domain Knowledge
- All prices stored in cents (integer) to avoid floating-point errors
- PII must not be logged (GDPR compliance)
- Payment via Stripe webhooks (see src/webhooks/stripe.ts)
```
---
## What's Good ✅
- ✅ Has Project Type and Tech Stack sections
- ✅ File structure is clear
- ✅ Uses markdown formatting consistently
---
## Next Steps
1. **Fix Critical Issues** (required for Claude to use agents automatically):
- Update routing rules to use WHEN/AUTOMATICALLY pattern
- Add plugin prefix to agent references
2. **Address Warnings** (improves effectiveness):
- Add code examples to Project Patterns
- Add variations to routing rules
3. **Consider Info Items** (nice to have):
- Add Domain Knowledge section if applicable
4. **Test Your CLAUDE.md**:
- Ask Claude to "create a component" and verify it invokes engineering/frontend-engineer automatically
---
## Re-run Validation
After making fixes, run this agent again to verify improvements:
```
Invoke claude-md-validator to re-check CLAUDE.md
```
```
---
## Success Criteria
A CLAUDE.md passes validation when:
- ✅ Has all required sections (Project Type, Tech Stack, Routing Rules)
- ✅ Routing rules use WHEN/AUTOMATICALLY pattern
- ✅ Routing rules are specific (not vague)
- ✅ Installed plugins are listed
- ✅ Plugin references use correct plugin:agent format
- ✅ Includes code examples (not just descriptions)
- ✅ No critical issues detected
---
## Edge Cases
### Case 1: Minimal CLAUDE.md
If user has a very minimal CLAUDE.md (just Project Type and Tech Stack):
**Report**:
```markdown
## Status: MINIMAL (Not invalid, but can be improved)
Your CLAUDE.md is valid but minimal. To enable automatic agent usage:
1. Add "Installed Puerto Plugins" section
2. Add "Automatic Task Routing" with WHEN/AUTOMATICALLY rules
3. Add "Project Patterns" with code examples
Without routing rules, Claude won't automatically use your installed agents.
```
### Case 2: Perfect CLAUDE.md
If CLAUDE.md is excellent:
**Report**:
```markdown
# CLAUDE.md Validation Report
**Status**: ✅ EXCELLENT
## Summary
No issues found! Your CLAUDE.md follows all best practices.
## What's Great
✅ Specific WHEN/AUTOMATICALLY routing rules
✅ Concrete code examples in Project Patterns
✅ Installed plugins properly listed
✅ Routing rules grouped by category
✅ Uses OR for trigger variations
✅ Includes domain knowledge
Your CLAUDE.md is production-ready!
## Optional Enhancements
Consider these minor improvements:
- Add more trigger variations for edge cases
- Document additional project patterns as you discover them
- Update regularly when adding new plugins or changing tech stack
```
---
## Output Format
Always output a structured markdown report with:
1. **Status Badge**: PASS / NEEDS IMPROVEMENT / FAIL
2. **Summary**: Count of issues by severity
3. **Critical Issues**: Must-fix items with specific line numbers and fixes
4. **Warnings**: Should-fix items
5. **Info**: Nice-to-have suggestions
6. **What's Good**: Highlight positive aspects
7. **Next Steps**: Specific actions to take
---
## Best Practices
1. **Be Specific**: Always provide exact fixes, not vague suggestions
2. **Show Examples**: Include code examples in fixes
3. **Prioritize**: Critical issues first, then warnings, then info
4. **Be Constructive**: Highlight what's good, not just what's wrong
5. **Be Actionable**: Every issue should have a clear fix
6. **Be Fast**: Haiku model enables quick validation
7. **Be Educational**: Explain WHY something is an issue
---
## Remember
- **Skills First**: Always load claude-md-syntax skill before validation
- **Best Practices Focus**: Check best practices, not pedantic syntax
- **Specific Fixes**: Provide exact fixes with line numbers
- **Constructive**: Highlight good patterns too
- **Actionable**: Every issue has a clear solution
You are the expert at validating CLAUDE.md files. Make validation fast, specific, and actionable so users can quickly improve their configuration.

708
agents/marketplace-integrator.md Normal file
View File

@@ -0,0 +1,708 @@
---
name: marketplace-integrator
description: PROACTIVELY use when optimizing CLAUDE.md for Puerto marketplace plugins. Intelligent plugin discovery agent that scans installed plugins and generates appropriate routing rules automatically.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---
# Marketplace Integrator Agent
You are a specialized agent for discovering installed Puerto plugins and enhancing CLAUDE.md with proper marketplace integration. You autonomously scan the filesystem for plugins, extract agent information, and generate comprehensive routing rules.
---
## CRITICAL: Skills-First Approach
**MANDATORY FIRST STEP**: Load all three skills before any integration work.
```bash
# Load claude-md-syntax skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/claude-md-syntax/SKILL.md ]; then
cat ~/.claude/skills/claude-md-syntax/SKILL.md
elif [ -f .claude/skills/claude-md-syntax/SKILL.md ]; then
cat ~/.claude/skills/claude-md-syntax/SKILL.md
elif [ -f plugins/claude-md-master/skills/claude-md-syntax/SKILL.md ]; then
cat plugins/claude-md-master/skills/claude-md-syntax/SKILL.md
else
echo "ERROR: claude-md-syntax skill not found"
exit 1
fi
# Load task-routing-patterns skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/task-routing-patterns/SKILL.md ]; then
cat ~/.claude/skills/task-routing-patterns/SKILL.md
elif [ -f .claude/skills/task-routing-patterns/SKILL.md ]; then
cat ~/.claude/skills/task-routing-patterns/SKILL.md
elif [ -f plugins/claude-md-master/skills/task-routing-patterns/SKILL.md ]; then
cat ~/.claude/skills/task-routing-patterns/SKILL.md
else
echo "ERROR: task-routing-patterns skill not found"
exit 1
fi
# Load marketplace-discovery skill (NON-NEGOTIABLE)
if [ -f ~/.claude/skills/marketplace-discovery/SKILL.md ]; then
cat ~/.claude/skills/marketplace-discovery/SKILL.md
elif [ -f .claude/skills/marketplace-discovery/SKILL.md ]; then
cat ~/.claude/skills/marketplace-discovery/SKILL.md
elif [ -f plugins/claude-md-master/skills/marketplace-discovery/SKILL.md ]; then
cat ~/.claude/skills/marketplace-discovery/SKILL.md
else
echo "ERROR: marketplace-discovery skill not found"
exit 1
fi
```
---
## When Invoked
When this agent is invoked, follow these steps:
### Step 1: Load Skills
- Load claude-md-syntax skill (CLAUDE.md specification)
- Load task-routing-patterns skill (routing patterns)
- Load marketplace-discovery skill (plugin discovery methods)
- Verify all skills loaded successfully
### Step 2: Read Existing CLAUDE.md (if exists)
```bash
# Check if CLAUDE.md exists
if [ -f CLAUDE.md ]; then
echo "✓ Found existing CLAUDE.md - will enhance it"
cat CLAUDE.md
else
echo "ℹ️ No CLAUDE.md found - will create new sections"
fi
```
### Step 3: Discover Installed Plugins
Run comprehensive plugin discovery:
```bash
#!/bin/bash
echo "🔍 Scanning for installed Puerto plugins..."
echo ""
# Function to extract agent info from markdown frontmatter
extract_agent_info() {
local agent_file="$1"
local plugin_name="$2"
if [ -f "$agent_file" ]; then
# Extract name (between --- markers, line starting with "name:")
agent_name=$(awk '/^---$/,/^---$/ { if (/^name:/) print $2 }' "$agent_file")
# Extract description (between --- markers, line starting with "description:")
agent_description=$(awk '/^---$/,/^---$/ { if (/^description:/) { sub(/^description: /, ""); print } }' "$agent_file")
# If description is multiline, get just the first line
agent_description=$(echo "$agent_description" | head -1)
echo "$plugin_name|$agent_name|$agent_description"
fi
}
# Array to store discovered plugin info
declare -a discovered_plugins
# Scan global plugins
if [ -d ~/.claude/plugins ]; then
for plugin_dir in ~/.claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
# Extract plugin info
plugin_name=$(jq -r '.name' "$plugin_json" 2>/dev/null)
if [ -n "$plugin_name" ] && [ "$plugin_name" != "null" ]; then
plugin_description=$(jq -r '.description' "$plugin_json" 2>/dev/null)
agent_files=$(jq -r '.agents[]' "$plugin_json" 2>/dev/null)
echo " ✓ Found: $plugin_name"
# For each agent, extract detailed info
for agent_file in $agent_files; do
full_agent_path="$plugin_dir/$agent_file"
if [ -f "$full_agent_path" ]; then
agent_info=$(extract_agent_info "$full_agent_path" "$plugin_name")
if [ -n "$agent_info" ]; then
discovered_plugins+=("$agent_info")
fi
fi
done
fi
fi
fi
done
fi
# Scan project-local plugins
if [ -d .claude/plugins ]; then
for plugin_dir in .claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
plugin_name=$(jq -r '.name' "$plugin_json" 2>/dev/null)
if [ -n "$plugin_name" ] && [ "$plugin_name" != "null" ]; then
plugin_description=$(jq -r '.description' "$plugin_json" 2>/dev/null)
agent_files=$(jq -r '.agents[]' "$plugin_json" 2>/dev/null)
echo " ✓ Found: $plugin_name (project-local)"
for agent_file in $agent_files; do
full_agent_path="$plugin_dir/$agent_file"
if [ -f "$full_agent_path" ]; then
agent_info=$(extract_agent_info "$full_agent_path" "$plugin_name")
if [ -n "$agent_info" ]; then
discovered_plugins+=("$agent_info")
fi
fi
done
fi
fi
fi
done
fi
echo ""
if [ ${#discovered_plugins[@]} -eq 0 ]; then
echo "⚠️ No Puerto plugins detected"
echo ""
echo "Install plugins with: /plugin install [plugin-name]"
echo ""
echo "Popular plugins:"
echo " - engineering (React/Vue/Svelte development)"
echo " - engineering (REST/GraphQL APIs)"
echo " - engineering (System architecture)"
echo " - engineering/devops-engineer (CI/CD and deployment)"
exit 0
else
echo "✅ Found ${#discovered_plugins[@]} agent(s) across installed plugins"
echo ""
# Output discovered info for processing
for agent_info in "${discovered_plugins[@]}"; do
echo "$agent_info"
done
fi
```
### Step 4: Organize Discovered Plugins
Group agents by plugin and category:
**Data Structure**:
```
plugins:
engineering:
- frontend-engineer: "PROACTIVELY use when implementing React/Vue/Svelte components..."
- state-architect: "PROACTIVELY use when implementing state management..."
- style-implementer: "PROACTIVELY use for responsive design and styling..."
engineering:
- backend-engineer: "PROACTIVELY use when implementing REST or GraphQL endpoints..."
- auth-implementer: "PROACTIVELY use when implementing API authentication..."
```
### Step 5: Generate "Installed Puerto Plugins" Section
Based on discovered plugins, generate:
```markdown
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React/Vue/Svelte components with TypeScript and tests
- state-architect: Implement state management (Redux, Zustand, Context)
- style-implementer: Responsive design and styling with CSS/Tailwind
### engineering
- backend-engineer: Create REST/GraphQL endpoints with validation and error handling
- auth-implementer: Implement JWT, OAuth 2.0, API key authentication with security best practices
- api-tester: Create comprehensive API integration tests with authentication and validation
### [other plugins...]
```
### Step 6: Generate Routing Rules from Agent Descriptions
Parse agent descriptions to extract trigger conditions and generate WHEN/AUTOMATICALLY rules:
**Description Parsing Logic**:
1. Look for "PROACTIVELY use when [condition]" pattern
2. Extract the condition
3. Generate WHEN/AUTOMATICALLY rule with variations
**Examples**:
**Input**: "PROACTIVELY use when implementing React/Vue/Svelte components"
**Output**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement [component name]" AND context is React/Vue/Svelte
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
**Input**: "PROACTIVELY use when implementing API authentication"
**Output**:
```markdown
WHEN user says "implement authentication" OR "add login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "set up [JWT/OAuth/API key] auth"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
### Step 7: Categorize Routing Rules
Group generated routing rules by category:
**Categories**:
- Frontend Development (if engineering, ux-researcher, accessibility-specialist)
- Backend Development (if engineering, engineering)
- Database Work (if database-architect)
- DevOps & Deployment (if engineering/devops-engineer, site-reliability-engineer)
- Testing & Quality (if test-runner, code-reviewer)
- Security (if security-auditor)
- Performance (if web-performance-auditor)
- Documentation (if technical-writer)
**Example Output**:
```markdown
## Automatic Task Routing
### Frontend Development
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement state management"
→ AUTOMATICALLY invoke: engineering:state-architect
### Backend Development
WHEN user says "create [endpoint] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement authentication"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
### Step 8: Merge with Existing CLAUDE.md
**Strategy**:
1. **Preserve** existing sections:
- Project Type
- Tech Stack
- Project Patterns
- Domain Knowledge
2. **Replace** marketplace sections:
- Installed Puerto Plugins
- Automatic Task Routing
3. **Smart Merge**:
- If user has custom routing rules, preserve them and add discovered ones
- If plugin already documented, update its entry
### Step 9: Output Enhanced CLAUDE.md
Present the enhanced file to the user:
```markdown
## Enhancement Summary
### Discovered Plugins
✓ engineering (3 agents)
✓ engineering (4 agents)
✓ engineering (3 agents)
### Generated Sections
✓ Installed Puerto Plugins (3 plugins, 10 agents)
✓ Automatic Task Routing (10 routing rules across 3 categories)
### Preserved Sections
✓ Project Type
✓ Tech Stack
✓ Project Patterns
✓ Domain Knowledge
---
## Preview of Enhanced CLAUDE.md
[Show first 100 lines]
...
---
Would you like me to:
1. Save enhanced CLAUDE.md (overwrites existing) ✅ Recommended
2. Save as CLAUDE.md.new (preserves original)
3. Show full enhanced file
4. Make adjustments (specify what to change)
```
### Step 10: Save Enhanced File
If user approves:
```bash
# Backup existing CLAUDE.md
if [ -f CLAUDE.md ]; then
cp CLAUDE.md CLAUDE.md.backup
echo "✓ Backed up existing CLAUDE.md to CLAUDE.md.backup"
fi
# Write enhanced CLAUDE.md
cat > CLAUDE.md << 'EOF'
[Enhanced CLAUDE.md content]
EOF
echo "✅ CLAUDE.md enhanced successfully!"
echo ""
echo "Summary:"
echo " - Added $plugin_count plugins"
echo " - Generated $routing_rule_count routing rules"
echo " - Preserved existing project patterns and domain knowledge"
echo ""
echo "Next steps:"
echo "1. Review the enhanced routing rules"
echo "2. Test: Ask Claude to perform tasks and verify agent invocation"
echo "3. Refine: Add custom routing rules if needed"
echo "4. Validate: Run claude-md-validator to check quality"
```
---
## Agent Description Parsing Patterns
### Pattern 1: "PROACTIVELY use when [condition]"
**Example**: "PROACTIVELY use when implementing React/Vue/Svelte components"
**Generated Rules**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: [plugin]:[agent]
WHEN user says "implement [component]"
→ AUTOMATICALLY invoke: [plugin]:[agent]
```
### Pattern 2: "Use for [task]"
**Example**: "Use for responsive design and styling"
**Generated Rules**:
```markdown
WHEN user says "style [component]"
→ AUTOMATICALLY invoke: [plugin]:[agent]
WHEN user says "make [component] responsive"
→ AUTOMATICALLY invoke: [plugin]:[agent]
```
### Pattern 3: Specific Technology Mention
**Example**: "Implement JWT, OAuth 2.0, API key authentication"
**Generated Rules**:
```markdown
WHEN user says "implement [JWT/OAuth/API key] authentication"
→ AUTOMATICALLY invoke: [plugin]:[agent]
WHEN user says "add authentication"
→ AUTOMATICALLY invoke: [plugin]:[agent]
```
### Pattern 4: Action Verb + Object
**Example**: "Create REST/GraphQL endpoints"
**Generated Rules**:
```markdown
WHEN user says "create [endpoint name] endpoint"
→ AUTOMATICALLY invoke: [plugin]:[agent]
WHEN user says "add API route for [resource]"
→ AUTOMATICALLY invoke: [plugin]:[agent]
```
---
## Category Mapping
### Frontend Category
**Plugins**: engineering, ux-researcher, ux-writer, accessibility-specialist
**Agents**: frontend-engineer, state-architect, style-implementer, accessibility-validator
**Section**:
```markdown
### Frontend Development
[Routing rules for frontend agents]
```
### Backend Category
**Plugins**: engineering, engineering
**Agents**: backend-engineer, auth-implementer, api-designer, system-architect
**Section**:
```markdown
### Backend Development
[Routing rules for backend agents]
```
### Database Category
**Plugins**: database-architect, engineering (database tasks)
**Agents**: query-optimizer, migration-manager, schema-designer, database-architect
**Section**:
```markdown
### Database Work
[Routing rules for database agents]
```
### DevOps Category
**Plugins**: engineering/devops-engineer, site-reliability-engineer
**Agents**: cicd-builder, deployment-orchestrator, infrastructure-manager, monitoring-setup
**Section**:
```markdown
### DevOps & Deployment
[Routing rules for DevOps agents]
```
---
## Smart Merge Logic
### Case 1: No Existing CLAUDE.md
**Action**: Create new CLAUDE.md with:
1. Minimal Project Type/Tech Stack (prompt user to fill in)
2. Generated "Installed Puerto Plugins" section
3. Generated "Automatic Task Routing" section
4. Placeholder for Project Patterns and Domain Knowledge
### Case 2: Existing CLAUDE.md with No Plugin Section
**Action**:
1. Preserve Project Type, Tech Stack, Patterns, Domain Knowledge
2. Insert "Installed Puerto Plugins" section after Tech Stack
3. Insert "Automatic Task Routing" section after Installed Plugins
### Case 3: Existing CLAUDE.md with Plugin Section
**Action**:
1. Preserve all non-plugin sections
2. Replace "Installed Puerto Plugins" with discovered plugins
3. Merge routing rules:
- Keep user's custom routing rules
- Add generated routing rules for newly discovered plugins
- Update routing rules for already-documented plugins
---
## Example Enhancement Flow
### Before (Existing CLAUDE.md)
```markdown
# My React App
## Project Type
React SPA with Express backend
## Tech Stack
- Frontend: React 18, Tailwind
- Backend: Express, PostgreSQL
## Project Patterns
### Component Structure
- Components in src/components/
- Use Tailwind for styling
```
### After Enhancement
```markdown
# My React App
## Project Type
React SPA with Express backend
## Tech Stack
- Frontend: React 18, Tailwind CSS
- Backend: Express, PostgreSQL
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React components with TypeScript and tests
- state-architect: Implement state management (Redux, Zustand, Context)
- style-implementer: Responsive design and styling with Tailwind
### engineering
- backend-engineer: Create REST endpoints with validation
- auth-implementer: Implement authentication (JWT, OAuth)
- api-tester: Create API integration tests
### engineering
- database-architect: Design database schemas and migrations
## Automatic Task Routing
### Frontend Development
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement state management"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "style [component]" OR "make [component] responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer
### Backend Development
WHEN user says "create [endpoint] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement authentication" OR "add login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "write tests for [API]" OR "add API tests"
→ AUTOMATICALLY invoke: engineering:api-tester
### Database Work
WHEN user says "design database schema" OR "create data model"
→ AUTOMATICALLY invoke: engineering/backend-engineer
## Project Patterns
### Component Structure
- Components in src/components/
- Use Tailwind for styling
```
---
## Edge Cases
### Case 1: No Plugins Installed
**Detection**: Discovery script returns empty array
**Action**:
```markdown
## No Plugins Detected
I didn't find any installed Puerto plugins.
Install popular plugins for your project type:
**For React SPA + Express Backend**:
- /plugin install engineering
- /plugin install engineering
- /plugin install engineering
After installing plugins, run me again to integrate them into CLAUDE.md.
```
### Case 2: Plugin Without Agent Descriptions
**Detection**: Agent frontmatter missing description field
**Action**: Use fallback description based on agent name:
```
frontend-engineer → "Create components"
backend-engineer → "Create API endpoints"
[agent-name] → "Handle [agent-name] tasks"
```
### Case 3: Malformed Plugin Manifest
**Detection**: jq fails to parse plugin.json
**Action**: Skip plugin and log warning:
```bash
echo "⚠️ Warning: Skipping plugin in $plugin_dir (malformed plugin.json)"
continue
```
---
## Quality Standards
Generated "Installed Puerto Plugins" section must:
- [ ] List all discovered plugins
- [ ] Include agent names and descriptions
- [ ] Use consistent formatting
- [ ] Group agents by plugin
Generated routing rules must:
- [ ] Use WHEN/AUTOMATICALLY pattern
- [ ] Be specific (not vague)
- [ ] Include trigger variations with OR
- [ ] Use [placeholders] for variables
- [ ] Reference plugins correctly (plugin:agent format)
- [ ] Be grouped by category
Enhanced CLAUDE.md must:
- [ ] Preserve existing non-plugin sections
- [ ] Follow official CLAUDE.md structure
- [ ] Be production-ready
- [ ] Include backup of original file
---
## Success Criteria
A successful marketplace integration should:
- ✅ Discover all installed plugins automatically
- ✅ Extract accurate agent information
- ✅ Generate specific routing rules from descriptions
- ✅ Preserve existing CLAUDE.md content
- ✅ Produce production-ready routing rules
- ✅ Categorize rules logically
- ✅ Create backup of original file
- ✅ Provide clear summary of changes
---
## Remember
- **Skills First**: Load all three skills before any work
- **Autonomous Discovery**: Scan filesystem, don't ask user to list plugins
- **Smart Merge**: Preserve existing content, enhance with marketplace data
- **Specific Rules**: Generate specific WHEN/AUTOMATICALLY patterns
- **Safe Operations**: Always backup existing CLAUDE.md
- **Clear Communication**: Show what was added/changed
You are the expert at integrating Puerto marketplace plugins into CLAUDE.md. Make the integration autonomous, intelligent, and preserve the user's existing configuration while enhancing it with marketplace plugin routing rules.

65
plugin.lock.json Normal file
View File

@@ -0,0 +1,65 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:bandofai/puerto:plugins/claude-md-master",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "2a833ffc71e40b2c806e0a3d5c66ccba835045d1",
"treeHash": "172f78330dddfbc1d215e1cfb8a4259c35e7255612d3406c8db5b3e4d3ee0a64",
"generatedAt": "2025-11-28T10:14:08.080306Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "claude-md-master",
"description": "Master CLAUDE.md configuration specialist. Creates, validates, and optimizes CLAUDE.md files with Puerto marketplace integration. Helps plugin developers generate production-ready CLAUDE.md with automatic task routing rules.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "bb85650fb600a23fc91e7d6b7a2d4655c1c042048955d9d2ef02cc2e1914eccc"
},
{
"path": "agents/claude-md-generator.md",
"sha256": "eca558cc1e57d05a59b956521f9bbd4a646636339295b2180d24bf83a9841943"
},
{
"path": "agents/marketplace-integrator.md",
"sha256": "efe3818f3c36b3be9610bccb2a8afe9a4805dc4f8bf5746de83f8fbb00466d69"
},
{
"path": "agents/claude-md-validator.md",
"sha256": "07248b06d53ec398e85d3c39faa54449df6bd55ebd242e4a0bb934dcbb2857e0"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "a8e391d8f6788ec73d0804eb3442cdeb2c1a48933313f40f369d2f99794cedaa"
},
{
"path": "skills/claude-md-syntax/SKILL.md",
"sha256": "d49ef76c75b57c9c3587906396ffcc0d74efa5cf4838ca499a4a8835c55de624"
},
{
"path": "skills/marketplace-discovery/SKILL.md",
"sha256": "e53ad011eec535c1dbc4691a9135b7f48be72f8aea9490b71399464d9350e4cf"
},
{
"path": "skills/task-routing-patterns/SKILL.md",
"sha256": "84864f2a68f8baf8f69d4ff161bcb3dbbe421ec095e70d5101c4dec6f99a758e"
}
],
"dirSha256": "172f78330dddfbc1d215e1cfb8a4259c35e7255612d3406c8db5b3e4d3ee0a64"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

899
skills/claude-md-syntax/SKILL.md Normal file
View File

@@ -0,0 +1,899 @@
# CLAUDE.md Syntax & Structure Specification
**Version**: 1.0.0
**Last Updated**: 2025-11-01
**Source**: Official Puerto documentation (configuring-claude-md.md)
---
## Purpose of This Skill
This skill provides comprehensive knowledge of CLAUDE.md syntax, structure, and best practices. It serves as the authoritative reference for all claude-md-master agents when creating, validating, or optimizing CLAUDE.md files.
**Key Learning Objectives**:
- Complete CLAUDE.md file structure and sections
- WHEN/AUTOMATICALLY routing rule patterns (THE CRITICAL FEATURE)
- Project-specific pattern documentation
- Common mistakes and their fixes
- Complete examples by project type
---
## What is CLAUDE.md?
CLAUDE.md is a configuration file that lives in a project's root directory and serves as an instruction manual for Claude Code. It tells Claude:
1. **Which Puerto plugins are installed** and available
2. **When to automatically use specific agents** (via routing rules)
3. **Project-specific patterns** to follow (file structure, code conventions)
4. **Domain knowledge** that helps agents make appropriate decisions
**The Result**: Claude proactively uses the right expert agents without manual specification every time.
### Why CLAUDE.md Matters
Without CLAUDE.md, Claude won't automatically know WHEN to use installed Puerto plugin agents. The file creates a "cascade effect":
```
User Request
↓
1. Claude reads CLAUDE.md → identifies task → selects agent
↓
2. Agent is invoked and reads CLAUDE.md → learns patterns → understands context
↓
3. Agent generates code matching project conventions
```
---
## Complete CLAUDE.md Structure
### Standard Sections (in order)
```markdown
# [Project Name]
## Project Type
[Brief description of what this project is]
## Tech Stack
- Frontend: [Technologies]
- Backend: [Technologies]
- Database: [Technologies]
- Testing: [Technologies]
- Deployment: [Platforms]
## Installed Puerto Plugins
- plugin-name (agents: agent1, agent2, agent3)
- plugin-name (agents: agent1, agent2)
## Automatic Task Routing
### [Category] Tasks
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
### [Category] Tasks
WHEN [trigger condition] → AUTOMATICALLY invoke: plugin-name:agent-name
## Project Patterns
### File Organization
[Directory structure with examples]
### [Pattern Category]
[Code examples and conventions]
## Domain Knowledge
[Business rules, constraints, integration points]
```
### Section Details
#### 1. Project Type & Tech Stack
**Purpose**: Give Claude immediate context about the project.
**Format**:
```markdown
## Project Type
[One sentence description, e.g., "React e-commerce SPA with Node.js API"]
## Tech Stack
- Frontend: [Specific libraries with versions if critical]
- Backend: [Runtime, framework, database]
- Testing: [Test frameworks]
- Deployment: [Hosting platforms]
```
**Example**:
```markdown
## Project Type
Full-stack e-commerce platform with React frontend and Express backend
## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS, React Query
- Backend: Node.js 20, Express, PostgreSQL 15, Prisma ORM
- Testing: Vitest, React Testing Library, Supertest
- Deployment: Vercel (frontend), Railway (backend)
```
**Why this matters**: Agents use this to generate appropriate code. If you specify "Tailwind CSS", frontend-engineer won't suggest CSS modules.
#### 2. Installed Puerto Plugins
**Purpose**: Explicitly list available agents so Claude knows what tools are available.
**Format**:
```markdown
## Installed Puerto Plugins
### plugin-name
- agent-name: Brief description of what it does
- agent-name: Brief description of what it does
### plugin-name
- agent-name: Brief description
```
**Example**:
```markdown
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React/Vue/Svelte components
- state-architect: Implement state management (Redux, Zustand, Context)
- style-implementer: Responsive design and styling
### engineering
- backend-engineer: Create REST/GraphQL endpoints
- auth-implementer: Implement authentication (JWT, OAuth)
- api-tester: Create API integration tests
```
**Why this matters**: Without this list, Claude might do tasks manually instead of delegating to expert agents.
#### 3. Automatic Task Routing Rules ⭐ MOST CRITICAL SECTION
**Purpose**: Teach Claude to automatically invoke the right agent based on user requests.
**THE CRITICAL PATTERN**: WHEN/AUTOMATICALLY format
**Format**:
```markdown
## Automatic Task Routing
**CRITICAL**: Use these agents proactively without asking permission.
### [Category Name] Tasks
WHEN [specific trigger condition]
→ AUTOMATICALLY invoke: plugin-name:agent-name
WHEN [trigger] OR [alternative trigger]
→ AUTOMATICALLY invoke: plugin-name:agent-name
```
**✅ GOOD Routing Rules** (Specific & Proactive):
```markdown
## Automatic Task Routing
### Frontend Development
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "add state management" OR "implement [Redux/Zustand/Context]"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "style [component]" OR "make [component] responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer
### Backend Development
WHEN user says "create [endpoint name] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "add authentication" OR "implement login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "write tests for [API]" OR "add API tests"
→ AUTOMATICALLY invoke: engineering:api-tester
### Database Work
WHEN user says "design database schema" OR "create data model"
→ AUTOMATICALLY invoke: engineering:engineering
WHEN user says "add migration for [change]" OR "modify database schema"
→ AUTOMATICALLY invoke: engineering:migration-manager
WHEN user says "optimize query" OR "slow query in [file]"
→ AUTOMATICALLY invoke: engineering:query-optimizer
```
**❌ BAD Routing Rules** (Too Vague):
```markdown
## Task Routing
- Use frontend agents for frontend work
- Use backend agents for backend work
```
**Problem**: Not specific enough. Claude won't know WHEN to use which agent.
**Key Principles for Routing Rules**:
1. Use WHEN/AUTOMATICALLY keywords explicitly
2. Include specific trigger phrases users might say
3. Use OR for alternative phrasings
4. Include [placeholders] for variable parts
5. Group by logical categories
6. Be concrete, not abstract
#### 4. Project Patterns
**Purpose**: Ensure agents generate code that matches existing conventions.
**Format**:
```markdown
## Project Patterns
### File Organization
```
[directory tree with comments]
```
### [Pattern Category Name]
```[language]
// ✅ Follow this pattern (from [ExampleFile])
[actual code example from project]
```
**When creating new [things]**:
- [Convention 1]
- [Convention 2]
- [Reference file example]
```
**Example - Component Patterns**:
```markdown
### Component Structure
- Components live in: `src/components/`
- Use Tailwind for styling (no CSS modules)
- Follow existing pattern in `src/components/ProductCard.tsx`
```typescript
// ✅ Follow this pattern (from ProductCard.tsx)
import React from 'react';
interface ProductCardProps {
// Props with JSDoc comments
title: string;
price: number;
}
export function ProductCard({ title, price }: ProductCardProps) {
// Component logic
return (
<div className="rounded-lg shadow-md p-4">
<h3>{title}</h3>
<p>${price}</p>
</div>
);
}
```
**When creating new components**:
- Use named exports (not default)
- TypeScript interfaces for props
- Tailwind for styling
- Follow existing component structure
```
**Example - API Patterns**:
```markdown
### API Conventions
- REST endpoints in: `src/api/routes/`
- Use Zod for request validation
- Follow pattern in `src/api/routes/products.ts`
```typescript
// ✅ Follow this pattern (from src/api/routes/products.ts)
import { Router } from 'express';
import { z } from 'zod';
import { validateRequest } from '../middleware/validation';
const router = Router();
// Zod schema for validation
const createProductSchema = z.object({
name: z.string(),
price: z.number(),
});
// Route handler with validation
router.post('/products', validateRequest(createProductSchema), async (req, res) => {
// Handler logic
});
export default router;
```
**When creating new endpoints**:
- Use Zod for request validation
- Async/await for handlers
- Consistent error handling middleware
- Follow REST conventions
```
**Why this matters**: Agents read these patterns and generate code that looks like it was written by the project team.
#### 5. Domain Knowledge
**Purpose**: Business context that helps agents make domain-appropriate decisions.
**Format**:
```markdown
## Domain Knowledge
### [Domain Area] Business Rules
- **[Rule Name]**: [Description with specifics]
- **[Rule Name]**: [Description]
### Critical Constraints
- [Constraint with reasoning]
- [Constraint with reasoning]
### Integration Points
- [External service description and reference file]
- [External service description and reference file]
```
**Example**:
```markdown
## Domain Knowledge
### E-commerce Business Rules
- **Products have variants**: Size, color, material (stored as separate SKUs)
- **Pricing calculation**: Base price + variant price + tax (by region)
- **Inventory**: Tracked per variant, not per product
- **Cart lifetime**: 24 hours for guest users, 30 days for authenticated
- **Payment processing**: Stripe for cards, PayPal for alternative payment
### Critical Constraints
- All prices stored in cents (integer) to avoid floating-point errors
- Product images must be optimized (<200KB) before storage
- PII (personally identifiable information) must not be logged
- GDPR compliance required: data deletion within 30 days of request
### Integration Points
- Stripe webhooks handle payment confirmations (see `src/webhooks/stripe.ts`)
- SendGrid for transactional emails (see `src/services/email.ts`)
- Cloudinary for image storage and transformation
```
**Why this matters**: Without this context, an agent might create a pricing system that uses floats (causing rounding errors) or log user emails (violating privacy).
---
## Common Mistakes & How to Fix Them
### ❌ Mistake 1: Vague Routing Rules
**Bad**:
```markdown
## Task Routing
Use frontend agents for frontend work
```
**Problem**: Not specific enough. Claude won't know when to invoke agents.
**✅ Fix**:
```markdown
## Automatic Task Routing
WHEN user says "create [component name] component" OR "add [component name]"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "style [component]" OR "make responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer
```
### ❌ Mistake 2: Not Listing Installed Plugins
**Bad**:
```markdown
# My Project
## Project Patterns
[Goes straight to patterns without listing plugins]
```
**Problem**: Claude doesn't know which agents are available.
**✅ Fix**:
```markdown
## Installed Puerto Plugins
- engineering
- engineering
- engineering
## Automatic Task Routing
[Then routing rules that reference these plugins]
```
### ❌ Mistake 3: Missing Project Patterns
**Bad**:
```markdown
## Project Patterns
We use React and Tailwind
```
**Problem**: Too vague. Agents don't know file structure, naming conventions, etc.
**✅ Fix**:
```markdown
## Project Patterns
### Component Structure
- Location: `src/components/[Name].tsx`
- Styling: Tailwind classes (see ProductCard.tsx for example)
- Props: TypeScript interfaces
```typescript
// Follow this pattern from ProductCard.tsx
export function ProductCard({ title, price }: Props) {
return <div className="rounded-lg shadow-md">...</div>;
}
```
```
### ❌ Mistake 4: Information Overload
**Bad**:
```markdown
[50 pages of detailed documentation about every aspect of the project]
```
**Problem**: Too much information. Claude gets overwhelmed and misses key points.
**✅ Fix**:
```markdown
## Key Points
- Component location: `src/components/`
- Styling: Tailwind only
- API routes: `src/api/routes/`
- Example component: See ProductCard.tsx
- Example API: See src/api/routes/products.ts
[Focus on most important patterns, reference files for details]
```
### ❌ Mistake 5: Outdated Information
**Bad**:
```markdown
## Tech Stack
- React 16
- Redux for state
[Project has since upgraded to React 18 and removed Redux]
```
**Problem**: Agents generate code for the wrong stack.
**✅ Fix**:
- Update when upgrading libraries
- Update when adding/removing plugins
- Update when changing patterns
- Review quarterly for accuracy
---
## Complete Examples by Project Type
### Example 1: React SPA with REST API
**Scenario**: E-commerce frontend in React, backend in Node.js/Express
**Plugins**: engineering, engineering, engineering
```markdown
# ShopHub - E-commerce Platform
## Project Type
React single-page application (SPA) with Node.js REST API backend
## Tech Stack
- Frontend: React 18, TypeScript, Tailwind CSS, React Query, React Router
- Backend: Node.js 20, Express, PostgreSQL 15, Prisma ORM
- Testing: Vitest, React Testing Library, Supertest
- Deployment: Vercel (frontend), Railway (backend)
## Installed Puerto Plugins
- engineering (frontend-engineer, state-architect, style-implementer)
- engineering (backend-engineer, auth-implementer, api-tester)
- engineering (api-designer, engineering)
## Automatic Task Routing
### Frontend Tasks
WHEN creating components → AUTOMATICALLY invoke engineering/frontend-engineer
WHEN implementing state → AUTOMATICALLY invoke engineering:state-architect
WHEN styling → AUTOMATICALLY invoke engineering:style-implementer
### Backend Tasks
WHEN creating endpoints → AUTOMATICALLY invoke engineering/backend-engineer
WHEN adding authentication → AUTOMATICALLY invoke engineering/backend-engineer
WHEN designing APIs → AUTOMATICALLY invoke engineering:api-designer
### Database Tasks
WHEN designing schemas → AUTOMATICALLY invoke engineering:engineering
## Project Patterns
### Component Structure
- Location: `src/components/[ComponentName].tsx`
- Styling: Tailwind classes only (no CSS modules)
- Props: TypeScript interfaces with JSDoc
- Exports: Named exports (not default)
- Example: See `src/components/ProductCard.tsx`
### API Structure
- Routes: `src/api/routes/[resource].ts`
- Validation: Zod schemas
- Auth: JWT middleware in `src/api/middleware/auth.ts`
- Example: See `src/api/routes/products.ts`
### State Management
- Global state: React Query for server state
- Local state: useState/useReducer
- Auth state: Custom useAuth hook
- No Redux (explicitly avoided)
## Domain Knowledge
- Products have variants (size, color) as separate SKUs
- Prices in cents (integer) to avoid floating-point errors
- Cart expires after 24 hours (guest) or 30 days (authenticated)
- Payment via Stripe webhooks
- GDPR compliance: no PII in logs
```
### Example 2: Node.js Microservices
**Scenario**: Backend-only microservices architecture
**Plugins**: engineering, engineering, engineering/devops-engineer, engineering
```markdown
# PaymentProcessor - Microservices Platform
## Project Type
Node.js microservices architecture with event-driven communication
## Tech Stack
- Runtime: Node.js 20, TypeScript
- Framework: Express, NestJS (auth service)
- Message Queue: RabbitMQ
- Databases: PostgreSQL (transactions), Redis (cache), MongoDB (logs)
- Testing: Jest, Supertest
- Deployment: Kubernetes (AWS EKS)
## Installed Puerto Plugins
- engineering (backend-engineer, auth-implementer, api-tester)
- engineering (api-designer, engineering, system-architect)
- engineering/devops-engineer (cicd-builder, deployment-orchestrator, infrastructure-manager)
- engineering (schema-designer, migration-manager, query-optimizer)
## Automatic Task Routing
### API Development
WHEN creating endpoints → AUTOMATICALLY invoke engineering/backend-engineer
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
WHEN writing API tests → AUTOMATICALLY invoke engineering:api-tester
### Architecture
WHEN designing APIs → AUTOMATICALLY invoke engineering:api-designer
WHEN designing schemas → AUTOMATICALLY invoke engineering:engineering
WHEN designing system architecture → AUTOMATICALLY invoke engineering:system-architect
### Database
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
WHEN optimizing queries → AUTOMATICALLY invoke engineering:query-optimizer
### DevOps
WHEN setting up CI/CD → AUTOMATICALLY invoke engineering/devops-engineer:cicd-builder
WHEN deploying → AUTOMATICALLY invoke engineering/devops-engineer:deployment-orchestrator
WHEN creating infrastructure → AUTOMATICALLY invoke engineering/devops-engineer:infrastructure-manager
## Project Patterns
### Service Structure
```
services/
├── auth-service/ # NestJS service
├── payment-service/ # Express service
├── notification-service/ # Express service
└── shared/ # Shared libraries
```
### API Conventions
- All services expose: `/health`, `/metrics`, `/ready`
- OpenAPI spec required for all services
- REST for sync, RabbitMQ for async
- Correlation IDs for request tracing
### Event Patterns
```typescript
// Publisher pattern
await messageQueue.publish('payment.processed', {
correlationId: req.id,
payload: { orderId, amount, status }
});
// Consumer pattern
messageQueue.subscribe('payment.processed', async (message) => {
// Handle event
});
```
### Database Patterns
- PostgreSQL for transactional data (ACID required)
- MongoDB for append-only logs
- Redis for caching and session storage
- Migrations: Knex.js for PostgreSQL
- Connection pooling: 20 max connections per service
## Domain Knowledge
- Payment processing: PCI DSS compliance required
- Idempotency: All payment endpoints must be idempotent (use idempotency keys)
- Event ordering: Use RabbitMQ with consistent hash exchange
- Retry logic: Exponential backoff with max 3 retries
- Circuit breaker: Fail fast after 5 consecutive errors
```
### Example 3: Full-Stack Next.js App
**Scenario**: Next.js with API routes and PostgreSQL
**Plugins**: engineering, engineering, engineering
```markdown
# TaskMaster - Project Management SaaS
## Project Type
Full-stack Next.js 14 application with App Router and server actions
## Tech Stack
- Framework: Next.js 14 (App Router), TypeScript, React 18
- Styling: Tailwind CSS, Shadcn UI components
- Database: PostgreSQL 15 with Drizzle ORM
- Auth: NextAuth.js v5
- Deployment: Vercel
## Installed Puerto Plugins
- engineering (frontend-engineer, state-architect, style-implementer)
- engineering (backend-engineer, auth-implementer)
- engineering (schema-designer, migration-manager, query-optimizer)
## Automatic Task Routing
### Frontend
WHEN creating components → AUTOMATICALLY invoke engineering/frontend-engineer
WHEN implementing client state → AUTOMATICALLY invoke engineering:state-architect
### Backend
WHEN creating API routes → AUTOMATICALLY invoke engineering/backend-engineer
WHEN creating server actions → AUTOMATICALLY invoke engineering/backend-engineer
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
### Database
WHEN designing schemas → AUTOMATICALLY invoke engineering:schema-designer
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
WHEN optimizing queries → AUTOMATICALLY invoke engineering:query-optimizer
## Project Patterns
### File Structure (App Router)
```
app/
├── (auth)/ # Auth group
│ ├── login/
│ └── signup/
├── (dashboard)/ # Protected group
│ ├── projects/
│ └── tasks/
├── api/ # API routes
└── actions/ # Server actions
components/
├── ui/ # Shadcn components
└── [feature]/ # Feature components
```
### Component Patterns
- Use Shadcn UI components as base
- Server Components by default
- Client Components only when needed (mark with 'use client')
- Co-locate components with routes when route-specific
### Server Actions Pattern
```typescript
// app/actions/tasks.ts
'use server';
import { revalidatePath } from 'next/cache';
import { auth } from '@/lib/auth';
export async function createTask(formData: FormData) {
const session = await auth();
if (!session) throw new Error('Unauthorized');
// Business logic
revalidatePath('/dashboard/tasks');
}
```
### Database Patterns
- Drizzle ORM for type-safe queries
- Schemas in: `db/schema.ts`
- Migrations in: `db/migrations/`
- Use transactions for multi-table operations
- Index frequently queried columns
## Domain Knowledge
- Multi-tenancy: All data scoped to workspaceId
- Permissions: Role-based (owner, admin, member)
- Real-time: Use Supabase Realtime for live updates
- Webhooks: Stripe for billing, Slack for notifications
- Data retention: Soft delete with 30-day retention before hard delete
```
---
## Advanced Patterns
### Context-Specific Routing
Route differently based on file location:
```markdown
## Context-Specific Routing
WHEN working in `src/admin/` directory
→ Use admin-specific patterns (verbose logging, strict validation)
WHEN working in `src/public-api/` directory
→ Use public API patterns (rate limiting, thorough docs)
```
### Conditional Plugin Usage
```markdown
## Conditional Agent Usage
WHEN implementing payment features
→ MUST invoke: engineering/backend-engineer (for PCI compliance)
→ MUST add: Audit logging
WHEN implementing user data features
→ MUST consider: GDPR compliance (no PII in logs)
```
### Reference External Docs
```markdown
## Reference Documentation
For API design patterns: See `docs/api-guidelines.md`
For component library: See Storybook at `http://localhost:6006`
For database schema: See ER diagram at `docs/schema.png`
```
### Plugin Combinations for Complex Tasks
```markdown
## Complex Task Routing
WHEN user says "create new feature with [frontend + backend]"
→ First invoke: engineering:system-architect (design architecture)
→ Then invoke: engineering/frontend-engineer (build UI)
→ Then invoke: engineering/backend-engineer (build API)
→ Then invoke: engineering:schema-designer (design schema)
This ensures proper architecture before implementation.
```
---
## Validation Checklist
Use this checklist when validating CLAUDE.md files:
### Structure Validation
- [ ] Has Project Type section
- [ ] Has Tech Stack section
- [ ] Has Installed Puerto Plugins section
- [ ] Has Automatic Task Routing section
- [ ] Has Project Patterns section (optional but recommended)
- [ ] Has Domain Knowledge section (optional but recommended)
### Routing Rules Validation
- [ ] Uses WHEN/AUTOMATICALLY keywords
- [ ] Routing rules are specific (not vague)
- [ ] Includes trigger phrases users might say
- [ ] Uses OR for alternative phrasings
- [ ] Groups rules by logical categories
- [ ] References installed plugins correctly
### Pattern Validation
- [ ] Includes concrete code examples
- [ ] References actual project files
- [ ] Specifies file locations
- [ ] Documents naming conventions
- [ ] Shows technology usage (not just lists)
### Domain Knowledge Validation
- [ ] Includes business rules if applicable
- [ ] Documents critical constraints
- [ ] Lists integration points
- [ ] Explains "why" not just "what"
### Quality Validation
- [ ] Concise (not information overload)
- [ ] Up to date (matches current tech stack)
- [ ] Actionable (agents can follow patterns)
- [ ] Consistent (formatting throughout)
---
## Maintenance Best Practices
### Keep It Updated
Track changes:
```markdown
## Change Log
- 2025-11-01: Added engineering plugin
- 2025-10-15: Migrated from Redux to React Query
- 2025-09-20: Upgraded to React 18
```
### Version Control
Commit to repository:
```bash
git add CLAUDE.md
git commit -m "docs: add CLAUDE.md with routing rules for Puerto plugins"
```
### Iterative Improvement
1. **Start simple**: Basic routing rules and patterns
2. **Observe**: See how Claude uses it
3. **Refine**: Add specificity where Claude gets confused
4. **Expand**: Add domain knowledge as needed
---
## Summary: Key Principles
1. **CLAUDE.md guides agent selection** - Without it, Claude won't automatically use installed plugins
2. **Be specific in routing rules** - Use WHEN/AUTOMATICALLY format with concrete task descriptions
3. **Document patterns with examples** - Show actual code from the project that agents should follow
4. **Include domain knowledge** - Business context helps agents make appropriate decisions
5. **Keep it maintained** - Update when changing tech stack or patterns
6. **Test and iterate** - Start simple, observe behavior, refine based on results
---
**End of CLAUDE.md Syntax Specification**
This skill should be loaded at the start of every claude-md-master agent invocation to ensure complete and accurate knowledge of CLAUDE.md structure, syntax, and best practices.

646
skills/marketplace-discovery/SKILL.md Normal file
View File

@@ -0,0 +1,646 @@
# Puerto Marketplace Discovery & Integration
**Version**: 1.0.0
**Last Updated**: 2025-11-01
**Purpose**: Comprehensive guide to discovering and integrating Puerto marketplace plugins
---
## Purpose of This Skill
This skill provides knowledge for autonomously discovering installed Puerto plugins and generating appropriate CLAUDE.md integration sections. Use this when the marketplace-integrator agent needs to scan plugins and create routing rules.
**Key Learning Objectives**:
- Understand Puerto marketplace structure (140+ plugins, 27 squads)
- Learn how to discover installed plugins via filesystem
- Extract agent descriptions from plugin manifests
- Generate routing rules from agent descriptions
- Create comprehensive "Installed Puerto Plugins" sections
---
## Puerto Marketplace Overview
### Structure
- **Total Plugins**: 140+
- **Organization**: 27 specialized squads
- **Installation Locations**:
- Global: `~/.claude/plugins/`
- Project-local: `.claude/plugins/`
### Plugin Structure
Every Puerto plugin follows this consistent structure:
```
~/.claude/plugins/[plugin-name]/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── agents/
│ ├── agent1.md # Agent markdown files
│ ├── agent2.md
│ └── agent3.md
├── skills/
│ └── skill-name/
│ └── SKILL.md # Skill content
├── commands/ # Optional
│ └── command.md
└── README.md
```
---
## Plugin Discovery Process
### Step 1: Scan Installation Directories
Check both global and project-local plugin directories:
```bash
# Discover installed plugins
for plugin_dir in ~/.claude/plugins/* .claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
# Plugin found - extract info
echo "Found plugin: $plugin_dir"
fi
fi
done
```
### Step 2: Read Plugin Manifest
Extract key information from `plugin.json`:
```bash
# Read plugin.json
plugin_name=$(jq -r '.name' "$plugin_json")
plugin_description=$(jq -r '.description' "$plugin_json")
agent_files=$(jq -r '.agents[]' "$plugin_json")
```
**Example plugin.json**:
```json
{
"name": "engineering",
"version": "1.0.0",
"description": "Frontend development specialist for React/Vue/Svelte",
"agents": [
"./agents/frontend-engineer.md",
"./agents/state-architect.md",
"./agents/style-implementer.md"
],
"skills": [
"./skills/component-patterns.md"
],
"author": {
"name": "Puerto Plugin Collection"
}
}
```
### Step 3: Extract Agent Information
Read agent frontmatter from markdown files:
```bash
# For each agent file, extract frontmatter
for agent_file in $agent_files; do
full_path="$plugin_dir/$agent_file"
# Extract name from frontmatter
agent_name=$(grep '^name:' "$full_path" | sed 's/name: //')
# Extract description (contains trigger conditions)
agent_description=$(grep '^description:' "$full_path" | sed 's/description: //')
echo "Agent: $agent_name"
echo "Description: $agent_description"
done
```
**Example agent frontmatter**:
```markdown
---
name: frontend-engineer
description: PROACTIVELY use when implementing React/Vue/Svelte components. Skill-aware builder that produces production-ready components with TypeScript and tests.
tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet
---
```
### Step 4: Generate Routing Rules from Descriptions
Parse agent descriptions to extract trigger conditions:
**Pattern**: Descriptions often contain "PROACTIVELY use when [trigger condition]"
**Example**:
- Description: "PROACTIVELY use when implementing React/Vue/Svelte components"
- Generated rule: `WHEN implementing components → AUTOMATICALLY invoke: engineering/frontend-engineer`
---
## Puerto Plugin Categories (27 Squads)
### 1. Frontend Development Squad
- **engineering**: React/Vue/Svelte component development
- **ux-researcher**: User research and usability testing
- **ux-writer**: UX writing and microcopy
- **accessibility-specialist**: WCAG compliance and a11y
### 2. Backend Development Squad
- **engineering**: REST/GraphQL endpoint development
- **engineering**: API design, database schemas, system architecture
### 3. Database Squad
- **engineering**: Query optimization, migrations, schema design
### 4. DevOps Squad
- **engineering/devops-engineer**: CI/CD, deployment, infrastructure
- **site-reliability-engineer**: SRE practices, monitoring, incident response
### 5. Testing Squad
- **test-runner**: Test execution
- **code-reviewer**: Code quality review
### 6. Security Squad
- **security-auditor**: Security scanning and audits
### 7. Performance Squad
- **web-performance-auditor**: Lighthouse audits, performance optimization
### 8. Documentation Squad
- **technical-writer**: Documentation generation
### 9. Business Squad
- **business-analyst**: Business analysis and requirements
- **sales-proposal-writer**: Sales proposal creation
### 10. Data Squad
- **data-analyst**: Data analysis
- **ml-engineer**: Machine learning engineering
### 11-27. Additional Squads
(Add more as discovered during scanning)
---
## Generating "Installed Puerto Plugins" Section
### Format Template
```markdown
## Installed Puerto Plugins
### [plugin-name]
- [agent-name]: [Brief description of what it does]
- [agent-name]: [Brief description]
- [agent-name]: [Brief description]
### [plugin-name]
- [agent-name]: [Brief description]
```
### Example Generation
**Input** (discovered plugins):
- engineering (3 agents)
- engineering (3 agents)
- engineering (3 agents)
**Output** (CLAUDE.md section):
```markdown
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React/Vue/Svelte components with TypeScript
- state-architect: Implement state management (Redux, Zustand, Context)
- style-implementer: Responsive design and styling with CSS/Tailwind
### engineering
- backend-engineer: Create REST/GraphQL endpoints with validation
- auth-implementer: Implement JWT, OAuth 2.0, API key authentication
- api-tester: Create comprehensive API integration tests
### engineering
- query-optimizer: Analyze and optimize slow database queries
- migration-manager: Create zero-downtime database migrations
- schema-designer: Design normalized database schemas and ER diagrams
```
---
## Generating Routing Rules from Plugin Discovery
### Process
1. **Extract trigger conditions** from agent descriptions
2. **Map to WHEN/AUTOMATICALLY pattern**
3. **Group by category** (Frontend, Backend, Database, etc.)
4. **Add variations** for common phrasings
### Example: Frontend-Developer Plugin
**Discovered Agents**:
1. frontend-engineer: "PROACTIVELY use when creating React/Vue/Svelte components"
2. state-architect: "PROACTIVELY use when implementing state management"
3. style-implementer: "PROACTIVELY use for responsive design and styling"
**Generated Routing Rules**:
```markdown
## Automatic Task Routing
### Frontend Development
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement state management" OR "add [Redux/Zustand/Context]"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "style [component]" OR "make [component] responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer
```
### Example: API-Developer Plugin
**Discovered Agents**:
1. backend-engineer: "PROACTIVELY use when implementing REST or GraphQL endpoints"
2. auth-implementer: "PROACTIVELY use when implementing API authentication"
3. api-tester: "PROACTIVELY use when creating API integration tests"
**Generated Routing Rules**:
```markdown
### Backend Development
WHEN user says "create [endpoint name] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement authentication" OR "add login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "write tests for [API]" OR "add API tests"
→ AUTOMATICALLY invoke: engineering:api-tester
```
---
## Common Plugin Patterns
### Pattern 1: Multi-Agent Specialist Plugins
Plugins with 3-5 agents covering different aspects of a domain:
**Examples**:
- **engineering**: frontend-engineer, state-architect, style-implementer, accessibility-validator
- **engineering**: backend-engineer, auth-implementer, api-tester, openapi-generator
- **engineering/devops-engineer**: cicd-builder, deployment-orchestrator, infrastructure-manager, monitoring-setup
**Integration Strategy**: Create subsections for each aspect:
```markdown
### [Plugin] Tasks
#### Component Creation
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent1]
#### State Management
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent2]
#### Styling
WHEN... → AUTOMATICALLY invoke: [plugin]:[agent3]
```
### Pattern 2: Single-Purpose Auditor Plugins
Plugins with 1-2 agents focused on specific analysis:
**Examples**:
- **accessibility-specialist**: accessibility-auditor, remediation-consultant
- **security-auditor**: security-scanner
- **web-performance-auditor**: lighthouse-auditor, performance-analyzer
**Integration Strategy**: Simple routing rules:
```markdown
### Quality Assurance
WHEN user says "audit accessibility"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor
WHEN user says "check security"
→ AUTOMATICALLY invoke: security-auditor:security-scanner
```
### Pattern 3: Workflow Plugins
Plugins with agents representing workflow stages:
**Examples**:
- **engineering**: api-designer (design) → engineering (schema) → system-architect (infrastructure)
**Integration Strategy**: Sequential routing:
```markdown
### Architecture & Design
WHEN designing new feature
→ First invoke: engineering:system-architect (architecture)
→ Then invoke: engineering:engineering (schema)
→ Then invoke: engineering:api-designer (API spec)
```
---
## Plugin Discovery Bash Script
Complete script for discovering and analyzing installed plugins:
```bash
#!/bin/bash
# PLUGIN DISCOVERY SCRIPT
# Scans ~/.claude/plugins/ and .claude/plugins/ for installed Puerto plugins
echo "=== Discovering Installed Puerto Plugins ==="
echo ""
# Array to store discovered plugins
declare -a discovered_plugins
# Scan global plugins
if [ -d ~/.claude/plugins ]; then
echo "Scanning global plugins: ~/.claude/plugins/"
for plugin_dir in ~/.claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
plugin_name=$(jq -r '.name' "$plugin_json")
plugin_description=$(jq -r '.description' "$plugin_json")
agent_count=$(jq '.agents | length' "$plugin_json")
echo " ✓ Found: $plugin_name ($agent_count agents)"
discovered_plugins+=("$plugin_name|$plugin_dir|$agent_count")
fi
fi
done
fi
# Scan project-local plugins
if [ -d .claude/plugins ]; then
echo "Scanning project plugins: .claude/plugins/"
for plugin_dir in .claude/plugins/*; do
if [ -d "$plugin_dir" ]; then
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
if [ -f "$plugin_json" ]; then
plugin_name=$(jq -r '.name' "$plugin_json")
plugin_description=$(jq -r '.description' "$plugin_json")
agent_count=$(jq '.agents | length' "$plugin_json")
echo " ✓ Found: $plugin_name ($agent_count agents)"
discovered_plugins+=("$plugin_name|$plugin_dir|$agent_count")
fi
fi
done
fi
echo ""
echo "=== Total Plugins Found: ${#discovered_plugins[@]} ==="
echo ""
# Extract agent details for each plugin
for plugin_info in "${discovered_plugins[@]}"; do
IFS='|' read -r plugin_name plugin_dir agent_count <<< "$plugin_info"
echo "## $plugin_name ($agent_count agents)"
plugin_json="$plugin_dir/.claude-plugin/plugin.json"
agent_files=$(jq -r '.agents[]' "$plugin_json")
for agent_file in $agent_files; do
full_path="$plugin_dir/$agent_file"
if [ -f "$full_path" ]; then
# Extract agent name and description from frontmatter
agent_name=$(grep '^name:' "$full_path" | head -1 | sed 's/name: //')
agent_description=$(grep '^description:' "$full_path" | head -1 | sed 's/description: //')
echo " - $agent_name: $agent_description"
fi
done
echo ""
done
```
---
## Integration Workflow
### Step-by-Step Process for marketplace-integrator Agent
1. **Run Discovery Script**
- Execute bash script to scan plugin directories
- Collect plugin names, descriptions, and agent details
2. **Read Existing CLAUDE.md** (if it exists)
- Check if "Installed Puerto Plugins" section exists
- Identify plugins already documented
3. **Generate New Content**
- Create "Installed Puerto Plugins" section with discovered plugins
- Generate routing rules based on agent descriptions
- Group rules by logical categories
4. **Merge with Existing Content**
- Preserve existing Project Type, Tech Stack, Patterns
- Replace/update "Installed Puerto Plugins" section
- Replace/update "Automatic Task Routing" section
- Keep Domain Knowledge intact
5. **Output Enhanced CLAUDE.md**
- Return complete updated file
- Highlight what was added/changed
---
## Example: Complete Integration Output
**Before** (user's existing CLAUDE.md):
```markdown
# My React App
## Project Type
React SPA with Express backend
## Tech Stack
- Frontend: React 18, Tailwind
- Backend: Express, PostgreSQL
```
**After** (marketplace-integrator enhancement):
```markdown
# My React App
## Project Type
React SPA with Express backend
## Tech Stack
- Frontend: React 18, Tailwind CSS
- Backend: Express, PostgreSQL
## Installed Puerto Plugins
### engineering
- frontend-engineer: Create React components with TypeScript
- state-architect: Implement state management
- style-implementer: Responsive design with Tailwind
### engineering
- backend-engineer: Create REST endpoints
- auth-implementer: Implement authentication
- api-tester: Create API tests
### engineering
- engineering: Design database schemas
## Automatic Task Routing
### Frontend Development
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement state management"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "style [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer
### Backend Development
WHEN user says "create [endpoint] endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement authentication"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "write API tests"
→ AUTOMATICALLY invoke: engineering:api-tester
### Database Work
WHEN user says "design database schema"
→ AUTOMATICALLY invoke: engineering:engineering
```
---
## Handling Edge Cases
### Case 1: No Plugins Installed
**Detection**: Discovery script returns empty array
**Action**: Inform user and suggest installing plugins:
```markdown
## Installed Puerto Plugins
No Puerto plugins detected. Install plugins with:
`/plugin install [plugin-name]`
Popular plugins for this project type:
- engineering (for React development)
- engineering (for Express APIs)
- engineering (for PostgreSQL schemas)
```
### Case 2: Plugin Without Agents
**Detection**: `plugin.json` has empty agents array
**Action**: Skip plugin or note it in comments:
```markdown
<!-- Plugin 'example-plugin' found but has no agents -->
```
### Case 3: Malformed plugin.json
**Detection**: `jq` fails to parse
**Action**: Log error and skip plugin:
```bash
if ! jq empty "$plugin_json" 2>/dev/null; then
echo "Warning: Malformed plugin.json in $plugin_dir (skipping)"
continue
fi
```
### Case 4: Agent File Missing Frontmatter
**Detection**: `grep` returns empty for name/description
**Action**: Use fallback values:
```bash
if [ -z "$agent_name" ]; then
# Extract from filename: "./agents/frontend-engineer.md" → "frontend-engineer"
agent_name=$(basename "$agent_file" .md)
fi
if [ -z "$agent_description" ]; then
agent_description="No description available"
fi
```
---
## Best Practices for Plugin Integration
1. **Always scan both global and project-local directories**
- Users might have plugins in either location
- Project-local plugins take precedence
2. **Preserve existing CLAUDE.md content**
- Don't overwrite Project Patterns or Domain Knowledge
- Only update "Installed Puerto Plugins" and "Automatic Task Routing"
3. **Generate routing rules from agent descriptions**
- Parse "PROACTIVELY use when..." patterns
- Add common trigger variations (create/add/implement)
4. **Group routing rules logically**
- Frontend, Backend, Database, DevOps, Testing, etc.
- Match categories to installed plugin types
5. **Include agent descriptions in plugin listings**
- Helps users understand what each agent does
- Creates self-documenting CLAUDE.md
6. **Handle errors gracefully**
- Skip malformed plugins
- Provide fallback descriptions
- Log warnings for users
---
## Summary: Plugin Discovery Checklist
When running marketplace-integrator agent:
- [ ] Scan `~/.claude/plugins/` for global plugins
- [ ] Scan `.claude/plugins/` for project-local plugins
- [ ] Read `plugin.json` for each discovered plugin
- [ ] Extract plugin name, description, agent list
- [ ] Read agent frontmatter for each agent
- [ ] Extract agent names and descriptions
- [ ] Generate "Installed Puerto Plugins" section
- [ ] Generate routing rules from agent descriptions
- [ ] Group routing rules by category
- [ ] Preserve existing CLAUDE.md sections
- [ ] Output enhanced CLAUDE.md
---
**End of Marketplace Discovery Skill**
This skill should be used by the marketplace-integrator agent when scanning installed plugins and generating CLAUDE.md integration sections.

760
skills/task-routing-patterns/SKILL.md Normal file
View File

@@ -0,0 +1,760 @@
# Task Routing Patterns for CLAUDE.md
**Version**: 1.0.0
**Last Updated**: 2025-11-01
**Purpose**: Comprehensive WHEN/AUTOMATICALLY routing patterns for Puerto marketplace plugins
---
## Purpose of This Skill
This skill provides battle-tested routing patterns for the most common Puerto plugins and task types. Use these patterns when generating or validating CLAUDE.md routing rules.
**Key Learning Objectives**:
- Master the WHEN/AUTOMATICALLY syntax
- Learn trigger phrases by plugin category
- Understand pattern templates for different task types
- Apply routing rules that maximize automatic agent invocation
---
## The WHEN/AUTOMATICALLY Pattern
### Core Syntax
```markdown
WHEN [trigger condition]
→ AUTOMATICALLY invoke: plugin-name:agent-name
```
### Key Elements
1. **WHEN**: Keyword that signals a trigger condition
2. **Trigger condition**: Specific phrase or pattern the user might say
3. **→**: Visual separator (arrow)
4. **AUTOMATICALLY invoke**: Explicit instruction to use agent without asking
5. **plugin-name:agent-name**: Full agent identifier
### Pattern Variations
**Single trigger**:
```markdown
WHEN user says "create component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
**Multiple triggers with OR**:
```markdown
WHEN user says "create component" OR "add component" OR "build component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
**Trigger with variable placeholders**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
**Combined placeholders and alternatives**:
```markdown
WHEN user says "create [endpoint name] endpoint" OR "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
---
## Frontend Development Patterns
### Frontend-Developer Plugin
#### Component Builder Agent
```markdown
### Component Tasks
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "add [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "build [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
WHEN user says "implement [component name]" AND context is React/Vue/Svelte
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
#### State Architect Agent
```markdown
### State Management Tasks
WHEN user says "add state management"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "implement [Redux/Zustand/Context/Recoil]"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "set up global state"
→ AUTOMATICALLY invoke: engineering:state-architect
WHEN user says "manage state for [feature]"
→ AUTOMATICALLY invoke: engineering:state-architect
```
#### Style Implementer Agent
```markdown
### Styling Tasks
WHEN user says "style [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer
WHEN user says "make [component] responsive"
→ AUTOMATICALLY invoke: engineering:style-implementer
WHEN user says "add CSS for [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer
WHEN user says "implement design for [component]"
→ AUTOMATICALLY invoke: engineering:style-implementer
```
---
## Backend Development Patterns
### API-Developer Plugin
#### Endpoint Builder Agent
```markdown
### API Endpoint Tasks
WHEN user says "create [endpoint name] endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "add API route for [resource]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement [REST/GraphQL] endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "build API for [feature]"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
#### Auth Implementer Agent
```markdown
### Authentication Tasks
WHEN user says "add authentication"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement login/signup"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "set up [JWT/OAuth/API key] auth"
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "add authorization middleware"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
#### API Tester Agent
```markdown
### API Testing Tasks
WHEN user says "write tests for [API]"
→ AUTOMATICALLY invoke: engineering:api-tester
WHEN user says "add API tests"
→ AUTOMATICALLY invoke: engineering:api-tester
WHEN user says "test [endpoint] endpoint"
→ AUTOMATICALLY invoke: engineering:api-tester
WHEN user says "create integration tests"
→ AUTOMATICALLY invoke: engineering:api-tester
```
---
## Database Patterns
### Backend-Architect Plugin (Database Tasks)
#### Database Architect Agent
```markdown
### Database Design Tasks
WHEN user says "design database schema"
→ AUTOMATICALLY invoke: engineering:engineering
WHEN user says "create data model"
→ AUTOMATICALLY invoke: engineering:engineering
WHEN user says "design ER diagram"
→ AUTOMATICALLY invoke: engineering:engineering
WHEN user says "model database for [feature]"
→ AUTOMATICALLY invoke: engineering:engineering
```
### Database-Architect Plugin
#### Migration Manager Agent
```markdown
### Migration Tasks
WHEN user says "add migration for [change]"
→ AUTOMATICALLY invoke: engineering:migration-manager
WHEN user says "modify database schema"
→ AUTOMATICALLY invoke: engineering:migration-manager
WHEN user says "create migration"
→ AUTOMATICALLY invoke: engineering:migration-manager
WHEN user says "alter table [table name]"
→ AUTOMATICALLY invoke: engineering:migration-manager
```
#### Query Optimizer Agent
```markdown
### Query Optimization Tasks
WHEN user says "optimize query" OR "slow query in [file]"
→ AUTOMATICALLY invoke: engineering:query-optimizer
WHEN user says "improve database performance"
→ AUTOMATICALLY invoke: engineering:query-optimizer
WHEN user says "add index for [column/table]"
→ AUTOMATICALLY invoke: engineering:query-optimizer
WHEN user says "fix N+1 queries in [file]"
→ AUTOMATICALLY invoke: engineering:query-optimizer
```
---
## DevOps Patterns
### DevOps-Engineer Plugin
#### CI/CD Builder Agent
```markdown
### CI/CD Tasks
WHEN user says "set up CI/CD"
→ AUTOMATICALLY invoke: engineering/devops-engineer:cicd-builder
WHEN user says "create [GitHub Actions/GitLab CI/Jenkins] pipeline"
→ AUTOMATICALLY invoke: engineering/devops-engineer:cicd-builder
WHEN user says "add automated testing to pipeline"
→ AUTOMATICALLY invoke: engineering/devops-engineer:cicd-builder
WHEN user says "configure deployment pipeline"
→ AUTOMATICALLY invoke: engineering/devops-engineer:cicd-builder
```
#### Deployment Orchestrator Agent
```markdown
### Deployment Tasks
WHEN user says "deploy to [environment]"
→ AUTOMATICALLY invoke: engineering/devops-engineer:deployment-orchestrator
WHEN user says "set up [blue-green/canary] deployment"
→ AUTOMATICALLY invoke: engineering/devops-engineer:deployment-orchestrator
WHEN user says "configure Kubernetes deployment"
→ AUTOMATICALLY invoke: engineering/devops-engineer:deployment-orchestrator
WHEN user says "implement rolling update"
→ AUTOMATICALLY invoke: engineering/devops-engineer:deployment-orchestrator
```
#### Infrastructure Manager Agent
```markdown
### Infrastructure Tasks
WHEN user says "create infrastructure"
→ AUTOMATICALLY invoke: engineering/devops-engineer:infrastructure-manager
WHEN user says "write [Terraform/CloudFormation] config"
→ AUTOMATICALLY invoke: engineering/devops-engineer:infrastructure-manager
WHEN user says "set up [AWS/GCP/Azure] resources"
→ AUTOMATICALLY invoke: engineering/devops-engineer:infrastructure-manager
WHEN user says "provision infrastructure for [service]"
→ AUTOMATICALLY invoke: engineering/devops-engineer:infrastructure-manager
```
---
## Accessibility Patterns
### Accessibility-Specialist Plugin
#### Accessibility Auditor Agent
```markdown
### Accessibility Audit Tasks
WHEN user says "audit accessibility"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor
WHEN user says "check WCAG compliance"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor
WHEN user says "test for accessibility issues"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor
WHEN user says "run accessibility scan"
→ AUTOMATICALLY invoke: accessibility-specialist:accessibility-auditor
```
#### Remediation Consultant Agent
```markdown
### Accessibility Fix Tasks
WHEN user says "fix accessibility issues in [component]"
→ AUTOMATICALLY invoke: accessibility-specialist:remediation-consultant
WHEN user says "make [component] accessible"
→ AUTOMATICALLY invoke: accessibility-specialist:remediation-consultant
WHEN user says "add ARIA labels to [component]"
→ AUTOMATICALLY invoke: accessibility-specialist:remediation-consultant
```
---
## Testing Patterns
### Code-Reviewer Plugin
```markdown
### Code Review Tasks
WHEN user says "review this code"
→ AUTOMATICALLY invoke: code-reviewer:code-reviewer
WHEN user says "check code quality"
→ AUTOMATICALLY invoke: code-reviewer:code-reviewer
WHEN user says "review [file] for issues"
→ AUTOMATICALLY invoke: code-reviewer:code-reviewer
```
### Test-Runner Plugin
```markdown
### Testing Tasks
WHEN user says "run tests"
→ AUTOMATICALLY invoke: test-runner:test-runner
WHEN user says "execute test suite"
→ AUTOMATICALLY invoke: test-runner:test-runner
WHEN user says "test [feature/file]"
→ AUTOMATICALLY invoke: test-runner:test-runner
```
---
## Documentation Patterns
### Technical-Writer Plugin
```markdown
### Documentation Tasks
WHEN user says "write documentation for [feature]"
→ AUTOMATICALLY invoke: technical-writer:documentation-generator
WHEN user says "create API docs"
→ AUTOMATICALLY invoke: technical-writer:api-documenter
WHEN user says "document [component/function/API]"
→ AUTOMATICALLY invoke: technical-writer:documentation-generator
WHEN user says "update README"
→ AUTOMATICALLY invoke: technical-writer:documentation-generator
```
---
## Security Patterns
### Security-Auditor Plugin
```markdown
### Security Tasks
WHEN user says "audit security"
→ AUTOMATICALLY invoke: security-auditor:security-scanner
WHEN user says "check for vulnerabilities"
→ AUTOMATICALLY invoke: security-auditor:security-scanner
WHEN user says "scan for security issues"
→ AUTOMATICALLY invoke: security-auditor:security-scanner
WHEN user says "review security in [file]"
→ AUTOMATICALLY invoke: security-auditor:code-reviewer
```
---
## Performance Patterns
### Web-Performance-Auditor Plugin
```markdown
### Performance Tasks
WHEN user says "audit performance"
→ AUTOMATICALLY invoke: web-performance-auditor:performance-analyzer
WHEN user says "run Lighthouse audit"
→ AUTOMATICALLY invoke: web-performance-auditor:lighthouse-auditor
WHEN user says "optimize [page/component] performance"
→ AUTOMATICALLY invoke: web-performance-auditor:optimization-recommender
WHEN user says "analyze load time"
→ AUTOMATICALLY invoke: web-performance-auditor:performance-analyzer
```
---
## Multi-Agent Task Patterns
### Complex Task Sequences
For tasks requiring multiple agents in sequence:
```markdown
### Full-Feature Implementation
WHEN user says "create new feature with [frontend + backend]"
→ First invoke: engineering:system-architect (design architecture)
→ Then invoke: engineering:engineering (design schema)
→ Then invoke: engineering/backend-engineer (build API)
→ Then invoke: engineering/frontend-engineer (build UI)
→ Then invoke: engineering:api-tester (test integration)
This ensures proper architecture design before implementation.
```
### Conditional Routing
For tasks with specific requirements:
```markdown
### Payment Feature Implementation
WHEN implementing payment features
→ MUST invoke: engineering/backend-engineer (for PCI compliance)
→ MUST invoke: security-auditor:security-scanner (security audit)
→ MUST add: Comprehensive audit logging
→ MUST follow: PCI DSS compliance guidelines
```
---
## Pattern Templates by Project Type
### React SPA Project
```markdown
## Automatic Task Routing
### Frontend Tasks
WHEN creating components → AUTOMATICALLY invoke engineering/frontend-engineer
WHEN implementing state → AUTOMATICALLY invoke engineering:state-architect
WHEN styling components → AUTOMATICALLY invoke engineering:style-implementer
WHEN testing components → AUTOMATICALLY invoke engineering:component-tester
### API Integration
WHEN calling APIs → AUTOMATICALLY invoke engineering/backend-engineer
WHEN handling auth → AUTOMATICALLY invoke engineering/backend-engineer
### Performance
WHEN optimizing performance → AUTOMATICALLY invoke web-performance-auditor:optimization-recommender
```
### Node.js Backend Project
```markdown
## Automatic Task Routing
### API Development
WHEN creating endpoints → AUTOMATICALLY invoke engineering/backend-engineer
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
WHEN writing API tests → AUTOMATICALLY invoke engineering:api-tester
### Database
WHEN designing schemas → AUTOMATICALLY invoke engineering:engineering
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
WHEN optimizing queries → AUTOMATICALLY invoke engineering:query-optimizer
### DevOps
WHEN setting up CI/CD → AUTOMATICALLY invoke engineering/devops-engineer:cicd-builder
WHEN deploying → AUTOMATICALLY invoke engineering/devops-engineer:deployment-orchestrator
```
### Full-Stack Next.js Project
```markdown
## Automatic Task Routing
### Frontend (Client Components)
WHEN creating client components → AUTOMATICALLY invoke engineering/frontend-engineer
WHEN implementing client state → AUTOMATICALLY invoke engineering:state-architect
### Backend (Server Components & Actions)
WHEN creating server actions → AUTOMATICALLY invoke engineering/backend-engineer
WHEN creating API routes → AUTOMATICALLY invoke engineering/backend-engineer
WHEN implementing auth → AUTOMATICALLY invoke engineering/backend-engineer
### Database
WHEN designing schemas → AUTOMATICALLY invoke engineering:schema-designer
WHEN creating migrations → AUTOMATICALLY invoke engineering:migration-manager
```
---
## Trigger Phrase Dictionary
### Action Verbs by Category
**Create/Build**:
- "create [thing]"
- "build [thing]"
- "add [thing]"
- "implement [thing]"
- "generate [thing]"
**Modify/Update**:
- "update [thing]"
- "modify [thing]"
- "change [thing]"
- "refactor [thing]"
- "improve [thing]"
**Test/Verify**:
- "test [thing]"
- "verify [thing]"
- "check [thing]"
- "validate [thing]"
- "audit [thing]"
**Fix/Optimize**:
- "fix [thing]"
- "optimize [thing]"
- "improve performance of [thing]"
- "debug [thing]"
- "resolve issues in [thing]"
**Design/Plan**:
- "design [thing]"
- "plan [thing]"
- "architect [thing]"
- "model [thing]"
---
## Best Practices for Routing Rules
### DO: Be Specific
✅ **Good**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
❌ **Bad**:
```markdown
WHEN doing frontend work
→ Use frontend agents
```
### DO: Include Variations
✅ **Good**:
```markdown
WHEN user says "create endpoint" OR "add API route" OR "build endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
❌ **Bad**:
```markdown
WHEN user says "create endpoint"
→ AUTOMATICALLY invoke: engineering/backend-engineer
```
### DO: Use Placeholders for Variables
✅ **Good**:
```markdown
WHEN user says "test [feature/component/API]"
→ AUTOMATICALLY invoke: test-runner:test-runner
```
❌ **Bad**:
```markdown
WHEN user says "test component"
→ AUTOMATICALLY invoke: test-runner:test-runner
```
### DO: Group by Category
✅ **Good**:
```markdown
### Frontend Tasks
[All frontend routing rules]
### Backend Tasks
[All backend routing rules]
### Database Tasks
[All database routing rules]
```
❌ **Bad**:
```markdown
WHEN create component → engineering/frontend-engineer
WHEN create endpoint → engineering/backend-engineer
WHEN create component tests → test-runner:test-runner
[Random order, no grouping]
```
### DO: Add Context When Needed
✅ **Good**:
```markdown
WHEN user says "implement [feature]" AND context is authentication
→ AUTOMATICALLY invoke: engineering/backend-engineer
WHEN user says "implement [feature]" AND context is payments
→ MUST invoke: security-auditor:security-scanner first
```
---
## Validation Patterns
When validating routing rules, check for:
1. **WHEN keyword present**
2. **Specific trigger phrases** (not vague)
3. **AUTOMATICALLY keyword** for proactive invocation
4. **Correct plugin:agent format**
5. **OR for variations** where applicable
6. **Placeholders** for variable parts [like this]
7. **Logical grouping** by category
8. **Installed plugins referenced** (not non-existent plugins)
---
## Common Routing Mistakes
### Mistake 1: Missing AUTOMATICALLY
❌ **Bad**:
```markdown
WHEN user says "create component"
→ invoke: engineering/frontend-engineer
```
✅ **Fix**:
```markdown
WHEN user says "create component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
### Mistake 2: Vague Triggers
❌ **Bad**:
```markdown
WHEN doing frontend stuff
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
✅ **Fix**:
```markdown
WHEN user says "create [component name] component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
### Mistake 3: Wrong Plugin Reference
❌ **Bad**:
```markdown
WHEN creating component
→ AUTOMATICALLY invoke: frontend-engineer
```
✅ **Fix**:
```markdown
WHEN creating component
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
### Mistake 4: No Variations
❌ **Bad**:
```markdown
WHEN user says "create component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
✅ **Fix**:
```markdown
WHEN user says "create component" OR "add component" OR "build component"
→ AUTOMATICALLY invoke: engineering/frontend-engineer
```
---
## Summary: Pattern Application
1. **Start with action verb** (create, add, implement, test, etc.)
2. **Add specific object** (component, endpoint, schema, etc.)
3. **Include variations** with OR
4. **Use placeholders** for variable parts [like this]
5. **Group by category** (Frontend, Backend, Database, etc.)
6. **Reference installed plugins** correctly (plugin-name:agent-name)
7. **Add AUTOMATICALLY** for proactive invocation
**Template**:
```markdown
### [Category] Tasks
WHEN user says "[verb] [object]" OR "[alternative verb] [object]"
→ AUTOMATICALLY invoke: plugin-name:agent-name
```
---
**End of Task Routing Patterns Skill**
This skill should be used alongside claude-md-syntax skill when generating or validating routing rules in CLAUDE.md files.