@ruaruababa/vibe-kit 1.0.0

package/skills/event-store-design/SKILL.md

@@ -0,0 +1,449 @@
+---
+name: event-store-design
+description: Design and implement event stores for event-sourced systems. Use when building event sourcing infrastructure, choosing event store technologies, or implementing event persistence patterns.
+---
+
+# Event Store Design
+
+Comprehensive guide to designing event stores for event-sourced applications.
+
+## Do not use this skill when
+
+- The task is unrelated to event store design
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Designing event sourcing infrastructure
+- Choosing between event store technologies
+- Implementing custom event stores
+- Optimizing event storage and retrieval
+- Setting up event store schemas
+- Planning for event store scaling
+
+## Core Concepts
+
+### 1. Event Store Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Event Store                       │
+├─────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │
+│  │   Stream 1   │  │   Stream 2   │  │   Stream 3   │ │
+│  │ (Aggregate)  │  │ (Aggregate)  │  │ (Aggregate)  │ │
+│  ├─────────────┤  ├─────────────┤  ├─────────────┤ │
+│  │ Event 1     │  │ Event 1     │  │ Event 1     │ │
+│  │ Event 2     │  │ Event 2     │  │ Event 2     │ │
+│  │ Event 3     │  │ ...         │  │ Event 3     │ │
+│  │ ...         │  │             │  │ Event 4     │ │
+│  └─────────────┘  └─────────────┘  └─────────────┘ │
+├─────────────────────────────────────────────────────┤
+│  Global Position: 1 → 2 → 3 → 4 → 5 → 6 → ...     │
+└─────────────────────────────────────────────────────┘
+```
+
+### 2. Event Store Requirements
+
+| Requirement       | Description                        |
+| ----------------- | ---------------------------------- |
+| **Append-only**   | Events are immutable, only appends |
+| **Ordered**       | Per-stream and global ordering     |
+| **Versioned**     | Optimistic concurrency control     |
+| **Subscriptions** | Real-time event notifications      |
+| **Idempotent**    | Handle duplicate writes safely     |
+
+## Technology Comparison
+
+| Technology       | Best For                  | Limitations                      |
+| ---------------- | ------------------------- | -------------------------------- |
+| **EventStoreDB** | Pure event sourcing       | Single-purpose                   |
+| **PostgreSQL**   | Existing Postgres stack   | Manual implementation            |
+| **Kafka**        | High-throughput streaming | Not ideal for per-stream queries |
+| **DynamoDB**     | Serverless, AWS-native    | Query limitations                |
+| **Marten**       | .NET ecosystems           | .NET specific                    |
+
+## Templates
+
+### Template 1: PostgreSQL Event Store Schema
+
+```sql
+-- Events table
+CREATE TABLE events (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    stream_id VARCHAR(255) NOT NULL,
+    stream_type VARCHAR(255) NOT NULL,
+    event_type VARCHAR(255) NOT NULL,
+    event_data JSONB NOT NULL,
+    metadata JSONB DEFAULT '{}',
+    version BIGINT NOT NULL,
+    global_position BIGSERIAL,
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+
+    CONSTRAINT unique_stream_version UNIQUE (stream_id, version)
+);
+
+-- Index for stream queries
+CREATE INDEX idx_events_stream_id ON events(stream_id, version);
+
+-- Index for global subscription
+CREATE INDEX idx_events_global_position ON events(global_position);
+
+-- Index for event type queries
+CREATE INDEX idx_events_event_type ON events(event_type);
+
+-- Index for time-based queries
+CREATE INDEX idx_events_created_at ON events(created_at);
+
+-- Snapshots table
+CREATE TABLE snapshots (
+    stream_id VARCHAR(255) PRIMARY KEY,
+    stream_type VARCHAR(255) NOT NULL,
+    snapshot_data JSONB NOT NULL,
+    version BIGINT NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Subscriptions checkpoint table
+CREATE TABLE subscription_checkpoints (
+    subscription_id VARCHAR(255) PRIMARY KEY,
+    last_position BIGINT NOT NULL DEFAULT 0,
+    updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Template 2: Python Event Store Implementation
+
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional, List
+from uuid import UUID, uuid4
+import json
+import asyncpg
+
+@dataclass
+class Event:
+    stream_id: str
+    event_type: str
+    data: dict
+    metadata: dict = field(default_factory=dict)
+    event_id: UUID = field(default_factory=uuid4)
+    version: Optional[int] = None
+    global_position: Optional[int] = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+
+class EventStore:
+    def __init__(self, pool: asyncpg.Pool):
+        self.pool = pool
+
+    async def append_events(
+        self,
+        stream_id: str,
+        stream_type: str,
+        events: List[Event],
+        expected_version: Optional[int] = None
+    ) -> List[Event]:
+        """Append events to a stream with optimistic concurrency."""
+        async with self.pool.acquire() as conn:
+            async with conn.transaction():
+                # Check expected version
+                if expected_version is not None:
+                    current = await conn.fetchval(
+                        "SELECT MAX(version) FROM events WHERE stream_id = $1",
+                        stream_id
+                    )
+                    current = current or 0
+                    if current != expected_version:
+                        raise ConcurrencyError(
+                            f"Expected version {expected_version}, got {current}"
+                        )
+
+                # Get starting version
+                start_version = await conn.fetchval(
+                    "SELECT COALESCE(MAX(version), 0) + 1 FROM events WHERE stream_id = $1",
+                    stream_id
+                )
+
+                # Insert events
+                saved_events = []
+                for i, event in enumerate(events):
+                    event.version = start_version + i
+                    row = await conn.fetchrow(
+                        """
+                        INSERT INTO events (id, stream_id, stream_type, event_type,
+                                          event_data, metadata, version, created_at)
+                        VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+                        RETURNING global_position
+                        """,
+                        event.event_id,
+                        stream_id,
+                        stream_type,
+                        event.event_type,
+                        json.dumps(event.data),
+                        json.dumps(event.metadata),
+                        event.version,
+                        event.created_at
+                    )
+                    event.global_position = row['global_position']
+                    saved_events.append(event)
+
+                return saved_events
+
+    async def read_stream(
+        self,
+        stream_id: str,
+        from_version: int = 0,
+        limit: int = 1000
+    ) -> List[Event]:
+        """Read events from a stream."""
+        async with self.pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT id, stream_id, event_type, event_data, metadata,
+                       version, global_position, created_at
+                FROM events
+                WHERE stream_id = $1 AND version >= $2
+                ORDER BY version
+                LIMIT $3
+                """,
+                stream_id, from_version, limit
+            )
+            return [self._row_to_event(row) for row in rows]
+
+    async def read_all(
+        self,
+        from_position: int = 0,
+        limit: int = 1000
+    ) -> List[Event]:
+        """Read all events globally."""
+        async with self.pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT id, stream_id, event_type, event_data, metadata,
+                       version, global_position, created_at
+                FROM events
+                WHERE global_position > $1
+                ORDER BY global_position
+                LIMIT $2
+                """,
+                from_position, limit
+            )
+            return [self._row_to_event(row) for row in rows]
+
+    async def subscribe(
+        self,
+        subscription_id: str,
+        handler,
+        from_position: int = 0,
+        batch_size: int = 100
+    ):
+        """Subscribe to all events from a position."""
+        # Get checkpoint
+        async with self.pool.acquire() as conn:
+            checkpoint = await conn.fetchval(
+                """
+                SELECT last_position FROM subscription_checkpoints
+                WHERE subscription_id = $1
+                """,
+                subscription_id
+            )
+            position = checkpoint or from_position
+
+        while True:
+            events = await self.read_all(position, batch_size)
+            if not events:
+                await asyncio.sleep(1)  # Poll interval
+                continue
+
+            for event in events:
+                await handler(event)
+                position = event.global_position
+
+            # Save checkpoint
+            async with self.pool.acquire() as conn:
+                await conn.execute(
+                    """
+                    INSERT INTO subscription_checkpoints (subscription_id, last_position)
+                    VALUES ($1, $2)
+                    ON CONFLICT (subscription_id)
+                    DO UPDATE SET last_position = $2, updated_at = NOW()
+                    """,
+                    subscription_id, position
+                )
+
+    def _row_to_event(self, row) -> Event:
+        return Event(
+            event_id=row['id'],
+            stream_id=row['stream_id'],
+            event_type=row['event_type'],
+            data=json.loads(row['event_data']),
+            metadata=json.loads(row['metadata']),
+            version=row['version'],
+            global_position=row['global_position'],
+            created_at=row['created_at']
+        )
+
+
+class ConcurrencyError(Exception):
+    """Raised when optimistic concurrency check fails."""
+    pass
+```
+
+### Template 3: EventStoreDB Usage
+
+```python
+from esdbclient import EventStoreDBClient, NewEvent, StreamState
+import json
+
+# Connect
+client = EventStoreDBClient(uri="esdb://localhost:2113?tls=false")
+
+# Append events
+def append_events(stream_name: str, events: list, expected_revision=None):
+    new_events = [
+        NewEvent(
+            type=event['type'],
+            data=json.dumps(event['data']).encode(),
+            metadata=json.dumps(event.get('metadata', {})).encode()
+        )
+        for event in events
+    ]
+
+    if expected_revision is None:
+        state = StreamState.ANY
+    elif expected_revision == -1:
+        state = StreamState.NO_STREAM
+    else:
+        state = expected_revision
+
+    return client.append_to_stream(
+        stream_name=stream_name,
+        events=new_events,
+        current_version=state
+    )
+
+# Read stream
+def read_stream(stream_name: str, from_revision: int = 0):
+    events = client.get_stream(
+        stream_name=stream_name,
+        stream_position=from_revision
+    )
+    return [
+        {
+            'type': event.type,
+            'data': json.loads(event.data),
+            'metadata': json.loads(event.metadata) if event.metadata else {},
+            'stream_position': event.stream_position,
+            'commit_position': event.commit_position
+        }
+        for event in events
+    ]
+
+# Subscribe to all
+async def subscribe_to_all(handler, from_position: int = 0):
+    subscription = client.subscribe_to_all(commit_position=from_position)
+    async for event in subscription:
+        await handler({
+            'type': event.type,
+            'data': json.loads(event.data),
+            'stream_id': event.stream_name,
+            'position': event.commit_position
+        })
+
+# Category projection ($ce-Category)
+def read_category(category: str):
+    """Read all events for a category using system projection."""
+    return read_stream(f"$ce-{category}")
+```
+
+### Template 4: DynamoDB Event Store
+
+```python
+import boto3
+from boto3.dynamodb.conditions import Key
+from datetime import datetime
+import json
+import uuid
+
+class DynamoEventStore:
+    def __init__(self, table_name: str):
+        self.dynamodb = boto3.resource('dynamodb')
+        self.table = self.dynamodb.Table(table_name)
+
+    def append_events(self, stream_id: str, events: list, expected_version: int = None):
+        """Append events with conditional write for concurrency."""
+        with self.table.batch_writer() as batch:
+            for i, event in enumerate(events):
+                version = (expected_version or 0) + i + 1
+                item = {
+                    'PK': f"STREAM#{stream_id}",
+                    'SK': f"VERSION#{version:020d}",
+                    'GSI1PK': 'EVENTS',
+                    'GSI1SK': datetime.utcnow().isoformat(),
+                    'event_id': str(uuid.uuid4()),
+                    'stream_id': stream_id,
+                    'event_type': event['type'],
+                    'event_data': json.dumps(event['data']),
+                    'version': version,
+                    'created_at': datetime.utcnow().isoformat()
+                }
+                batch.put_item(Item=item)
+        return events
+
+    def read_stream(self, stream_id: str, from_version: int = 0):
+        """Read events from a stream."""
+        response = self.table.query(
+            KeyConditionExpression=Key('PK').eq(f"STREAM#{stream_id}") &
+                                  Key('SK').gte(f"VERSION#{from_version:020d}")
+        )
+        return [
+            {
+                'event_type': item['event_type'],
+                'data': json.loads(item['event_data']),
+                'version': item['version']
+            }
+            for item in response['Items']
+        ]
+
+# Table definition (CloudFormation/Terraform)
+"""
+DynamoDB Table:
+  - PK (Partition Key): String
+  - SK (Sort Key): String
+  - GSI1PK, GSI1SK for global ordering
+
+Capacity: On-demand or provisioned based on throughput needs
+"""
+```
+
+## Best Practices
+
+### Do's
+
+- **Use stream IDs that include aggregate type** - `Order-{uuid}`
+- **Include correlation/causation IDs** - For tracing
+- **Version events from day one** - Plan for schema evolution
+- **Implement idempotency** - Use event IDs for deduplication
+- **Index appropriately** - For your query patterns
+
+### Don'ts
+
+- **Don't update or delete events** - They're immutable facts
+- **Don't store large payloads** - Keep events small
+- **Don't skip optimistic concurrency** - Prevents data corruption
+- **Don't ignore backpressure** - Handle slow consumers
+
+## Resources
+
+- [EventStoreDB](https://www.eventstore.com/)
+- [Marten Events](https://martendb.io/events/)
+- [Event Sourcing Pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/event-sourcing)

package/skills/fastapi-pro/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: fastapi-pro
+description: Build high-performance async APIs with FastAPI, SQLAlchemy 2.0, and
+  Pydantic V2. Master microservices, WebSockets, and modern Python async
+  patterns. Use PROACTIVELY for FastAPI development, async optimization, or API
+  architecture.
+metadata:
+  model: opus
+---
+
+## Use this skill when
+
+- Working on fastapi pro tasks or workflows
+- Needing guidance, best practices, or checklists for fastapi pro
+
+## Do not use this skill when
+
+- The task is unrelated to fastapi pro
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a FastAPI expert specializing in high-performance, async-first API development with modern Python patterns.
+
+## Purpose
+
+Expert FastAPI developer specializing in high-performance, async-first API development. Masters modern Python web development with FastAPI, focusing on production-ready microservices, scalable architectures, and cutting-edge async patterns.
+
+## Capabilities
+
+### Core FastAPI Expertise
+
+- FastAPI 0.100+ features including Annotated types and modern dependency injection
+- Async/await patterns for high-concurrency applications
+- Pydantic V2 for data validation and serialization
+- Automatic OpenAPI/Swagger documentation generation
+- WebSocket support for real-time communication
+- Background tasks with BackgroundTasks and task queues
+- File uploads and streaming responses
+- Custom middleware and request/response interceptors
+
+### Data Management & ORM
+
+- SQLAlchemy 2.0+ with async support (asyncpg, aiomysql)
+- Alembic for database migrations
+- Repository pattern and unit of work implementations
+- Database connection pooling and session management
+- MongoDB integration with Motor and Beanie
+- Redis for caching and session storage
+- Query optimization and N+1 query prevention
+- Transaction management and rollback strategies
+
+### API Design & Architecture
+
+- RESTful API design principles
+- GraphQL integration with Strawberry or Graphene
+- Microservices architecture patterns
+- API versioning strategies
+- Rate limiting and throttling
+- Circuit breaker pattern implementation
+- Event-driven architecture with message queues
+- CQRS and Event Sourcing patterns
+
+### Authentication & Security
+
+- OAuth2 with JWT tokens (python-jose, pyjwt)
+- Social authentication (Google, GitHub, etc.)
+- API key authentication
+- Role-based access control (RBAC)
+- Permission-based authorization
+- CORS configuration and security headers
+- Input sanitization and SQL injection prevention
+- Rate limiting per user/IP
+
+### Testing & Quality Assurance
+
+- pytest with pytest-asyncio for async tests
+- TestClient for integration testing
+- Factory pattern with factory_boy or Faker
+- Mock external services with pytest-mock
+- Coverage analysis with pytest-cov
+- Performance testing with Locust
+- Contract testing for microservices
+- Snapshot testing for API responses
+
+### Performance Optimization
+
+- Async programming best practices
+- Connection pooling (database, HTTP clients)
+- Response caching with Redis or Memcached
+- Query optimization and eager loading
+- Pagination and cursor-based pagination
+- Response compression (gzip, brotli)
+- CDN integration for static assets
+- Load balancing strategies
+
+### Observability & Monitoring
+
+- Structured logging with loguru or structlog
+- OpenTelemetry integration for tracing
+- Prometheus metrics export
+- Health check endpoints
+- APM integration (DataDog, New Relic, Sentry)
+- Request ID tracking and correlation
+- Performance profiling with py-spy
+- Error tracking and alerting
+
+### Deployment & DevOps
+
+- Docker containerization with multi-stage builds
+- Kubernetes deployment with Helm charts
+- CI/CD pipelines (GitHub Actions, GitLab CI)
+- Environment configuration with Pydantic Settings
+- Uvicorn/Gunicorn configuration for production
+- ASGI servers optimization (Hypercorn, Daphne)
+- Blue-green and canary deployments
+- Auto-scaling based on metrics
+
+### Integration Patterns
+
+- Message queues (RabbitMQ, Kafka, Redis Pub/Sub)
+- Task queues with Celery or Dramatiq
+- gRPC service integration
+- External API integration with httpx
+- Webhook implementation and processing
+- Server-Sent Events (SSE)
+- GraphQL subscriptions
+- File storage (S3, MinIO, local)
+
+### Advanced Features
+
+- Dependency injection with advanced patterns
+- Custom response classes
+- Request validation with complex schemas
+- Content negotiation
+- API documentation customization
+- Lifespan events for startup/shutdown
+- Custom exception handlers
+- Request context and state management
+
+## Behavioral Traits
+
+- Writes async-first code by default
+- Emphasizes type safety with Pydantic and type hints
+- Follows API design best practices
+- Implements comprehensive error handling
+- Uses dependency injection for clean architecture
+- Writes testable and maintainable code
+- Documents APIs thoroughly with OpenAPI
+- Considers performance implications
+- Implements proper logging and monitoring
+- Follows 12-factor app principles
+
+## Knowledge Base
+
+- FastAPI official documentation
+- Pydantic V2 migration guide
+- SQLAlchemy 2.0 async patterns
+- Python async/await best practices
+- Microservices design patterns
+- REST API design guidelines
+- OAuth2 and JWT standards
+- OpenAPI 3.1 specification
+- Container orchestration with Kubernetes
+- Modern Python packaging and tooling
+
+## Response Approach
+
+1. **Analyze requirements** for async opportunities
+2. **Design API contracts** with Pydantic models first
+3. **Implement endpoints** with proper error handling
+4. **Add comprehensive validation** using Pydantic
+5. **Write async tests** covering edge cases
+6. **Optimize for performance** with caching and pooling
+7. **Document with OpenAPI** annotations
+8. **Consider deployment** and scaling strategies
+
+## Example Interactions
+
+- "Create a FastAPI microservice with async SQLAlchemy and Redis caching"
+- "Implement JWT authentication with refresh tokens in FastAPI"
+- "Design a scalable WebSocket chat system with FastAPI"
+- "Optimize this FastAPI endpoint that's causing performance issues"
+- "Set up a complete FastAPI project with Docker and Kubernetes"
+- "Implement rate limiting and circuit breaker for external API calls"
+- "Create a GraphQL endpoint alongside REST in FastAPI"
+- "Build a file upload system with progress tracking"

package/skills/fastapi-templates/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: fastapi-templates
+description: Create production-ready FastAPI projects with async patterns, dependency injection, and comprehensive error handling. Use when building new FastAPI applications or setting up backend API projects.
+---
+
+# FastAPI Project Templates
+
+Production-ready FastAPI project structures with async patterns, dependency injection, middleware, and best practices for building high-performance APIs.
+
+## Use this skill when
+
+- Starting new FastAPI projects from scratch
+- Implementing async REST APIs with Python
+- Building high-performance web services and microservices
+- Creating async applications with PostgreSQL, MongoDB
+- Setting up API projects with proper structure and testing
+
+## Do not use this skill when
+
+- The task is unrelated to fastapi project templates
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.