shipdeck/lib/ultimate/agents/README.md

Ship MVPs in 48 hours. Fix bugs in 30 seconds. The command deck for developers who ship.

# Shipdeck Ultimate Agents

This directory contains specialized AI agents for backend development in the Shipdeck Ultimate template system.

## Available Agents

### BackendAgent (`backend-agent.js`)

A specialized agent for backend API development with the following capabilities:

**Core Features:**
- Express.js API generation
- RESTful endpoint creation
- CRUD operations
- Authentication & authorization
- Middleware development
- Input validation & sanitization
- Comprehensive error handling
- Test suite generation

**Capabilities:**
- `api` - RESTful API design and implementation
- `database` - Database operations and query optimization
- `authentication` - JWT tokens, OAuth2, session management
- `middleware` - Express middleware for validation, auth, etc.
- `routing` - Express routing with proper HTTP methods
- `validation` - Input validation and sanitization
- `error-handling` - Comprehensive error handling strategies

**Supported Task Types:**
- `generate-api` - Complete API structure with authentication
- `generate-crud` - CRUD operations for entities
- `generate-routes` - Express.js route definitions
- `generate-middleware` - Custom middleware functions
- `generate-auth` - Authentication system with JWT
- `generate-tests` - Comprehensive test suites

**Built-in Templates:**
- Basic Express routes with error handling
- CRUD controller with validation
- Authentication middleware
- Input validation schemas
- API test suites
- Error handling middleware

## Usage

### Basic Usage

```javascript
const { get } = require('./agent-registry');

// Get the backend agent
const backendAgent = get('backend-agent');

// Execute a task
const result = await backendAgent.execute({
  type: 'generate-api',
  description: 'User management API',
  requirements: [
    'CRUD operations for users',
    'JWT authentication', 
    'Input validation',
    'Comprehensive tests'
  ],
  entities: {
    User: {
      id: 'uuid',
      email: 'string',
      password: 'string',
      name: 'string'
    }
  }
});
```

### With Agent Registry

```javascript
const { register, get } = require('./agent-registry');
const BackendAgent = require('./backend-agent');

// Register agent (if not already registered)
register('backend-agent', new BackendAgent());

// Use the agent
const agent = get('backend-agent');
const result = await agent.executeWithRetry(task, context);
```

## Prerequisites

- Node.js 16+ 
- `@anthropic-ai/sdk` package
- `ANTHROPIC_API_KEY` environment variable

## Architecture

### BaseAgent (`base-agent.js`)

All agents extend the `BaseAgent` class which provides:
- Anthropic API client integration
- Task validation and execution
- Retry logic with exponential backoff
- Prompt generation and response parsing
- Logging and error handling
- Common utilities

### Agent Registry (`agent-registry.js`)

Centralized registry for managing agent instances:
- Registration and retrieval
- Singleton pattern for consistency
- Type-safe agent management

## Security Features

All generated backend code follows security best practices:
- Input validation and sanitization
- SQL injection prevention with parameterized queries
- JWT token validation
- Rate limiting implementation
- CORS configuration
- Environment variable usage for secrets
- Proper error handling without information leakage

## Testing

Generated code includes comprehensive test suites:
- Unit tests for business logic
- Integration tests for API endpoints
- Authentication flow testing
- Error scenario coverage
- Mocking and fixtures

## Next Steps

1. Install dependencies: `npm install @anthropic-ai/sdk`
2. Set API key: `export ANTHROPIC_API_KEY=your_key_here`
3. Register and use agents in your Shipdeck workflow
4. Extend with additional specialized agents as needed

## Contributing

When creating new agents:
1. Extend the `BaseAgent` class
2. Implement the `execute()` method
3. Define specific capabilities via `getCapabilities()`
4. Add comprehensive error handling
5. Include proper TypeScript types (avoid `any`)
6. Register with the agent registry