Initial commit
This commit is contained in:
Zhongwei Li
899
skills/claude-md-syntax/SKILL.md
Normal file
899
skills/claude-md-syntax/SKILL.md
Normal 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
646
skills/marketplace-discovery/SKILL.md
Normal 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
760
skills/task-routing-patterns/SKILL.md
Normal 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.
|
||||
Reference in New Issue
Block a user