# 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.