cortex-agents 1.0.1 → 2.1.0

package/.opencode/skills/architecture-patterns/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: architecture-patterns
+description: Microservices, monolith, event-driven, CQRS, hexagonal, clean architecture, serverless, and the twelve-factor methodology
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Architecture Patterns Skill
+
+This skill provides guidance on choosing and implementing software architecture patterns for scalable systems.
+
+## When to Use
+
+Use this skill when:
+- Designing new systems or services from scratch
+- Evaluating architecture for scaling or refactoring
+- Choosing between monolith, microservices, or serverless
+- Implementing event-driven, CQRS, or clean architecture
+- Making technology and infrastructure decisions
+
+## Architecture Decision Framework
+
+### Key Questions
+1. **Scale** — How many users/requests? Expected growth?
+2. **Team** — How large? How autonomous? How distributed?
+3. **Complexity** — How complex is the domain logic?
+4. **Velocity** — How fast do you need to ship?
+5. **Constraints** — Budget, compliance, existing infrastructure?
+
+### Quick Decision Matrix
+| Situation | Recommended Architecture |
+|-----------|--------------------------|
+| Small team, new product, uncertain requirements | Modular Monolith |
+| Large team, well-defined domains, independent deploy | Microservices |
+| High throughput, loose coupling, eventual consistency OK | Event-Driven |
+| Read-heavy with complex queries, different read/write models | CQRS |
+| Spiky workloads, pay-per-use, rapid prototyping | Serverless |
+| Complex domain logic, long-lived system | Clean/Hexagonal + DDD |
+
+## Monolithic Architecture
+
+### When to Use
+- Early-stage products — ship fast, iterate quickly
+- Small teams (< 10 developers)
+- Simple domain with clear boundaries
+- Shared database is acceptable
+
+### Modular Monolith (Recommended Starting Point)
+```
+src/
+  modules/
+    users/         # Self-contained user module
+      routes.ts
+      service.ts
+      repository.ts
+      models.ts
+    orders/        # Self-contained order module
+      routes.ts
+      service.ts
+      repository.ts
+      models.ts
+    shared/        # Shared kernel
+      auth/
+      database/
+      events/
+  app.ts
+```
+
+### Laravel Modular Monolith
+```
+app/
+  Modules/
+    Users/          # Self-contained user module
+      Controllers/
+      Models/
+      Services/
+      Repositories/
+      Routes/
+      Providers/UserServiceProvider.php
+    Orders/         # Self-contained order module
+      Controllers/
+      Models/
+      Services/
+      Events/
+      Providers/OrderServiceProvider.php
+  Providers/        # Core service providers
+```
+- Use Laravel service providers to register each module
+- Communicate between modules via events or defined interfaces
+- Laravel's service container makes modular DI natural
+- Can also use packages like `nwidart/laravel-modules`
+
+### Key Principles
+- Module boundaries enforced by convention or linting
+- Modules communicate through defined interfaces, not direct DB access
+- Each module owns its database tables
+- Can extract to microservices later with minimal refactoring
+
+### Strangler Fig Migration
+- Incrementally replace monolith functionality with new services
+- Route traffic through a facade that delegates to old or new
+- Never big-bang rewrite — decompose gradually
+
+## Microservices Architecture
+
+### Service Design
+- One service per business capability (bounded context)
+- Services own their data — no shared databases
+- API contracts between services (REST, gRPC, events)
+- Independent deployment and scaling
+
+### Communication Patterns
+| Pattern | Type | Use When |
+|---------|------|----------|
+| REST/gRPC | Synchronous | Request needs immediate response |
+| Message Queue | Asynchronous | Fire-and-forget, decoupled processing |
+| Event Bus | Asynchronous | Multiple consumers need to react |
+| Saga | Orchestrated | Distributed transactions across services |
+
+### Saga Pattern for Distributed Transactions
+```mermaid
+sequenceDiagram
+    participant OS as Order Service
+    participant PS as Payment Service
+    participant IS as Inventory Service
+    
+    OS->>PS: Process payment
+    PS-->>OS: Payment confirmed
+    OS->>IS: Reserve inventory
+    IS-->>OS: Inventory reserved
+    OS->>OS: Order confirmed
+    
+    Note over OS,IS: If any step fails,<br/>compensating actions<br/>undo previous steps
+```
+
+### Service Mesh & Discovery
+- Service discovery — Consul, Kubernetes DNS, AWS Cloud Map
+- Load balancing — round-robin, least connections, weighted
+- Circuit breaker — prevent cascade failures (Hystrix pattern)
+- Service mesh — Istio, Linkerd for observability and traffic management
+
+### Anti-Patterns to Avoid
+- Distributed monolith — services tightly coupled, must deploy together
+- Nano-services — too granular, excessive network overhead
+- Shared database — defeats data ownership principle
+- Synchronous chains — fragile, high latency
+
+## Event-Driven Architecture
+
+### Core Concepts
+- **Event** — Immutable fact that something happened
+- **Producer** — Service that emits events
+- **Consumer** — Service that reacts to events
+- **Event Bus** — Infrastructure for routing events (Kafka, RabbitMQ, NATS)
+
+### Event Types
+| Type | Description | Example |
+|------|-------------|---------|
+| Domain Event | Business-meaningful occurrence | `OrderPlaced`, `UserRegistered` |
+| Integration Event | Cross-boundary notification | `PaymentProcessed` |
+| Command Event | Request to perform action | `ProcessPayment` |
+
+### Event Sourcing
+- Store state as a sequence of events, not current snapshot
+- Rebuild state by replaying events from the beginning
+- Enables audit trail, temporal queries, debugging
+- **Trade-off**: Complex to implement, eventual consistency
+
+```
+Event Store:
+  1. OrderCreated { items: [...], userId: "123" }
+  2. ItemAdded { itemId: "abc", quantity: 2 }
+  3. PaymentProcessed { amount: 99.99 }
+  4. OrderShipped { trackingId: "XYZ" }
+
+Current State = replay(events) → Order { status: "shipped", ... }
+```
+
+### Best Practices
+- Events are immutable — never modify published events
+- Include correlation ID for tracing across services
+- Use schema registry for event versioning (Avro, Protobuf)
+- Dead letter queue for failed event processing
+- Idempotent consumers — safe to process the same event twice
+
+## CQRS (Command Query Responsibility Segregation)
+
+### Core Idea
+- Separate read model (queries) from write model (commands)
+- Read side optimized for queries — denormalized, cached
+- Write side optimized for business rules — normalized, validated
+
+```
+┌─────────────┐     ┌─────────────┐
+│   Command    │     │   Query     │
+│   (Write)    │     │   (Read)    │
+├─────────────┤     ├─────────────┤
+│ Validate     │     │ Optimized   │
+│ Business     │     │ Read Models │
+│ Rules        │     │ (Views)     │
+├─────────────┤     ├─────────────┤
+│ Write DB     │────>│ Read DB     │
+│ (Normalized) │event│ (Denorm.)   │
+└─────────────┘     └─────────────┘
+```
+
+### When to Use
+- Read and write workloads have very different characteristics
+- Complex domain logic on write side, simple queries on read side
+- Need to scale reads and writes independently
+- Combined with event sourcing for full audit trail
+
+### When NOT to Use
+- Simple CRUD applications — adds unnecessary complexity
+- Strong consistency required — read model has eventual consistency lag
+- Small team — operational overhead not justified
+
+## Clean / Hexagonal Architecture
+
+### Hexagonal Architecture (Ports & Adapters)
+```
+         ┌─────────────────────────────────┐
+         │          Adapters (Outer)        │
+         │  ┌─────────────────────────┐    │
+         │  │     Application Core     │    │
+         │  │  ┌───────────────────┐  │    │
+Driving  │  │  │                   │  │    │  Driven
+Adapters │  │  │   Domain Model    │  │    │  Adapters
+(API,    │──│──│  (Entities, Value │──│────│──(DB, Email,
+ CLI,    │  │  │   Objects, Rules) │  │    │   Queue,
+ Tests)  │  │  │                   │  │    │   External)
+         │  │  └───────────────────┘  │    │
+         │  │     Use Cases / Ports    │    │
+         │  └─────────────────────────┘    │
+         └─────────────────────────────────┘
+```
+
+### Key Rules
+- Domain has ZERO external dependencies — no frameworks, no DB
+- Ports (interfaces) define what the domain needs
+- Adapters implement ports — pluggable infrastructure
+- Dependencies point inward — outer layers depend on inner
+- Test domain logic without infrastructure
+
+### Clean Architecture Layers
+| Layer | Contains | Depends On |
+|-------|----------|------------|
+| Entities | Business objects, rules | Nothing |
+| Use Cases | Application logic, orchestration | Entities |
+| Interface Adapters | Controllers, presenters, gateways | Use Cases |
+| Frameworks | Web framework, DB, external services | Interface Adapters |
+
+## Serverless Architecture
+
+### Patterns
+- **API + Functions** — API Gateway + Lambda/Cloud Functions
+- **Event Processing** — Functions triggered by events (S3, Queue, DB)
+- **Scheduled Jobs** — CRON-triggered functions
+- **Step Functions** — Orchestrated workflows
+
+### Benefits
+- Zero idle cost — pay only for execution
+- Auto-scaling — from 0 to thousands of instances
+- No server management — focus on business logic
+
+### Limitations
+- Cold starts — latency spike on first invocation (mitigated with provisioned concurrency)
+- Execution duration limits (15 min Lambda, 60 min Cloud Run)
+- Stateless — no local state between invocations
+- Vendor lock-in — tight coupling to cloud provider APIs
+- Debugging complexity — distributed tracing required
+
+### Best Practices
+- Keep functions small and focused — one function, one purpose
+- Use environment variables for configuration
+- Implement structured logging with correlation IDs
+- Use layers/extensions for shared code
+- Test locally with emulators (SAM, serverless-offline, Functions Framework)
+
+## The Twelve-Factor App
+
+| # | Factor | Summary |
+|---|--------|---------|
+| 1 | Codebase | One codebase tracked in version control, many deploys |
+| 2 | Dependencies | Explicitly declare and isolate dependencies |
+| 3 | Config | Store config in environment variables |
+| 4 | Backing Services | Treat databases, queues, caches as attached resources |
+| 5 | Build, Release, Run | Strictly separate build, release, and run stages |
+| 6 | Processes | Execute app as stateless processes |
+| 7 | Port Binding | Export services via port binding |
+| 8 | Concurrency | Scale out via the process model |
+| 9 | Disposability | Fast startup, graceful shutdown |
+| 10 | Dev/Prod Parity | Keep development and production as similar as possible |
+| 11 | Logs | Treat logs as event streams |
+| 12 | Admin Processes | Run admin tasks as one-off processes |
+
+### Modern Additions
+- **API First** — Design APIs before implementation
+- **Telemetry** — Built-in observability (metrics, traces, logs)
+- **Security** — Security as a first-class concern, not an afterthought
+- **Authentication** — Externalize auth (OAuth, OIDC)
+
+## Data Architecture Patterns
+
+### Data Mesh
+- Domain-oriented data ownership — each team owns their data products
+- Data as a product — treat datasets with the same care as user-facing features
+- Self-serve data platform — infrastructure that enables domain teams
+- Federated governance — global policies, local implementation
+
+### Event Streaming Platform
+- Central event bus (Kafka, Pulumi) as source of truth
+- Services produce and consume events
+- Enables real-time analytics and derived views
+- Replay capability for rebuilding state
+
+### OLTP vs OLAP
+| Characteristic | OLTP | OLAP |
+|---------------|------|------|
+| Operations | INSERT, UPDATE, DELETE | SELECT, aggregate |
+| Queries | Simple, row-level | Complex, analytical |
+| Schema | Normalized (3NF) | Denormalized (star/snowflake) |
+| Examples | PostgreSQL, MySQL | BigQuery, Snowflake, ClickHouse |

package/.opencode/skills/backend-development/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: backend-development
+description: Server architecture, framework patterns, data access, caching, authentication, and error handling for backend applications
+license: Apache-2.0
+compatibility: opencode
+---
+
+# Backend Development Skill
+
+This skill provides patterns and best practices for building robust backend applications and services.
+
+## When to Use
+
+Use this skill when:
+- Building APIs or server-side applications
+- Choosing a backend framework or architecture
+- Implementing data access layers, caching, or auth
+- Setting up middleware, error handling, or background processing
+- Designing server architecture for scalability
+
+## Server Architecture
+
+### Layered Architecture
+```
+┌──────────────────────────┐
+│   Routes / Controllers   │  ← HTTP handling, validation
+├──────────────────────────┤
+│   Services / Use Cases   │  ← Business logic
+├──────────────────────────┤
+│   Repositories / DAL     │  ← Data access
+├──────────────────────────┤
+│   Database / External    │  ← Persistence, third-party
+└──────────────────────────┘
+```
+
+### Key Principles
+- Separate concerns — routes, business logic, data access in distinct layers
+- Dependency injection — invert dependencies for testability
+- Single responsibility — each module handles one concern
+- Fail fast — validate inputs at the boundary
+- Configuration via environment — never hardcode secrets or URLs
+
+## Framework Patterns
+
+### Node.js
+
+**Express** — Minimal, middleware-based
+```typescript
+// Layered Express app structure
+src/
+  routes/        // Route definitions, input validation
+  middleware/    // Auth, logging, error handling
+  services/     // Business logic
+  repositories/ // Database queries
+  models/       // Type definitions, schemas
+  utils/        // Shared utilities
+  app.ts        // Express app setup
+  server.ts     // Server startup
+```
+
+**Fastify** — Performance-focused, schema-based validation
+- Use JSON Schema for request/response validation (built-in)
+- Plugin system for encapsulated modules
+- Decorators for extending request/reply
+
+**NestJS** — Opinionated, Angular-inspired
+- Modules for feature encapsulation
+- Decorators for routing, validation, guards
+- Built-in DI container
+- Pipes, Guards, Interceptors for request pipeline
+
+### Python
+
+**FastAPI** — Modern, async, type-driven
+- Pydantic models for validation and serialization
+- Dependency injection via `Depends()`
+- Auto-generated OpenAPI docs
+- Background tasks with `BackgroundTasks`
+- Async database with SQLAlchemy + asyncpg
+
+**Django** — Batteries-included, ORM-centric
+- Models define schema and business rules
+- Class-based views for CRUD operations
+- Django REST Framework for API endpoints
+- Admin interface for quick data management
+- Middleware pipeline for cross-cutting concerns
+
+### Go
+
+**Gin/Echo** — Fast, minimal HTTP frameworks
+- Handler functions with context
+- Middleware chains for cross-cutting concerns
+- Struct tags for binding and validation
+- Goroutines for concurrent processing
+
+```go
+// Clean handler pattern in Go
+func (h *UserHandler) GetUser(c *gin.Context) {
+    id := c.Param("id")
+    user, err := h.service.FindByID(c.Request.Context(), id)
+    if err != nil {
+        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
+        return
+    }
+    c.JSON(http.StatusOK, user)
+}
+```
+
+### PHP
+
+**Laravel** — Full-featured, elegant, batteries-included
+```php
+// Layered Laravel app structure
+app/
+  Http/
+    Controllers/   // Route handlers, form requests
+    Middleware/     // Auth, CORS, rate limiting
+    Requests/       // Form request validation
+    Resources/      // API resource transformations
+  Models/           // Eloquent models
+  Services/         // Business logic
+  Repositories/     // Data access abstraction (optional)
+  Jobs/             // Queued background jobs
+  Events/           // Domain events
+  Listeners/        // Event handlers
+  Policies/         // Authorization logic
+routes/
+  api.php           // API routes
+  web.php           // Web routes
+```
+
+- Service container for dependency injection (auto-resolving)
+- Middleware pipeline (global, route groups, per-route)
+- Eloquent ORM with expressive Active Record pattern
+- Artisan CLI for code generation, migrations, and tasks
+- Built-in auth scaffolding (Breeze, Jetstream, Fortify)
+
+**Symfony** — Enterprise-grade, component-based
+- Bundle architecture for modular features
+- Doctrine ORM (Data Mapper pattern)
+- Flex for automated package configuration
+- Powerful DI container and event dispatcher
+- Strong enterprise and long-term support tradition
+
+### Rust
+
+**Actix Web / Axum** — Type-safe, async, performant
+- Extractors for type-safe request parsing
+- Tower middleware (Axum) for composable layers
+- Strong type system prevents runtime errors
+- Shared state via Arc<AppState>
+
+## Middleware & Request Pipeline
+
+### Common Middleware Stack (in order)
+1. **Request ID** — Generate unique ID for tracing
+2. **Logging** — Log request method, path, duration
+3. **CORS** — Configure allowed origins, methods, headers
+4. **Rate limiting** — Protect against abuse (token bucket, sliding window)
+5. **Authentication** — Verify JWT/session/API key
+6. **Authorization** — Check permissions for resource
+7. **Validation** — Validate request body, params, query
+8. **Handler** — Execute business logic
+9. **Error handler** — Catch and format errors consistently
+
+### Middleware Best Practices
+- Keep middleware focused — one concern each
+- Order matters — auth before authorization, logging first
+- Short-circuit early — return 401/403 before processing
+- Use async middleware for I/O-bound operations
+
+## Data Access
+
+### Repository Pattern
+```typescript
+// Abstract data access behind interfaces
+interface UserRepository {
+  findById(id: string): Promise<User | null>;
+  findByEmail(email: string): Promise<User | null>;
+  create(data: CreateUserDTO): Promise<User>;
+  update(id: string, data: UpdateUserDTO): Promise<User>;
+  delete(id: string): Promise<void>;
+}
+
+// Implement with your ORM of choice
+class PrismaUserRepository implements UserRepository {
+  constructor(private prisma: PrismaClient) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.prisma.user.findUnique({ where: { id } });
+  }
+  // ...
+}
+```
+
+### ORM Selection Guide
+| ORM | Language | Style | Best For |
+|-----|----------|-------|----------|
+| Prisma | TypeScript | Schema-first, type-safe | New Node.js projects |
+| Drizzle | TypeScript | SQL-like, lightweight | Performance-critical |
+| SQLAlchemy | Python | Flexible, powerful | Complex queries |
+| Django ORM | Python | Active Record | Django projects |
+| Eloquent | PHP | Active Record, expressive | Laravel projects |
+| Doctrine | PHP | Data Mapper, enterprise | Symfony projects |
+| GORM | Go | Convention-based | Go web apps |
+| Diesel | Rust | Compile-time checked | Rust applications |
+
+### Query Best Practices
+- Use parameterized queries — never string concatenation
+- Eager load relations to avoid N+1 queries
+- Paginate large result sets — cursor or offset-based
+- Use transactions for multi-step writes
+- Index frequently queried columns
+
+## Caching Strategies
+
+| Strategy | How It Works | Use Case |
+|----------|-------------|----------|
+| Cache-aside | App checks cache, falls back to DB | General purpose |
+| Read-through | Cache loads from DB on miss | Transparent caching |
+| Write-through | Write to cache and DB simultaneously | Consistency-critical |
+| Write-behind | Write to cache, async write to DB | High write throughput |
+
+### Implementation Patterns
+- **Redis** for distributed cache — sessions, rate limiting, computed results
+- **In-memory** (Map/LRU) for hot local data — config, feature flags
+- **CDN** for static assets and API responses with proper Cache-Control
+- **HTTP caching** — ETag, Last-Modified, Cache-Control headers
+
+### Cache Invalidation
+- TTL-based — set reasonable expiry times
+- Event-based — invalidate on write operations
+- Version-based — include version in cache key
+- Pattern: `cache:${entity}:${id}:${version}`
+
+## Authentication & Authorization
+
+### Authentication Methods
+| Method | Stateless | Best For |
+|--------|-----------|----------|
+| JWT (access + refresh) | Yes | SPAs, mobile apps |
+| Session cookies | No | Traditional web apps |
+| API keys | Yes | Service-to-service |
+| OAuth 2.0 / OIDC | Yes | Third-party login |
+
+### JWT Best Practices
+- Short-lived access tokens (15 min) + long-lived refresh tokens
+- Use RS256 or ES256 (asymmetric) over HS256 for distributed systems
+- Store refresh tokens in httpOnly cookies (not localStorage)
+- Implement token rotation on refresh
+- Include minimal claims — don't put sensitive data in payload
+
+### Authorization Patterns
+- **RBAC** (Role-Based) — user has roles, roles have permissions
+- **ABAC** (Attribute-Based) — policies based on user/resource attributes
+- **Resource-based** — check ownership before access
+- Centralize authorization logic — use middleware or decorators
+
+## Error Handling
+
+### Consistent Error Response
+```typescript
+// Standardized error response (RFC 7807 inspired)
+interface ErrorResponse {
+  status: number;       // HTTP status code
+  code: string;         // Machine-readable error code
+  message: string;      // Human-readable description
+  details?: unknown;    // Validation errors, context
+  requestId?: string;   // For support/debugging
+}
+```
+
+### HTTP Status Code Guide
+| Code | Meaning | Use When |
+|------|---------|----------|
+| 400 | Bad Request | Validation failure, malformed input |
+| 401 | Unauthorized | Missing or invalid authentication |
+| 403 | Forbidden | Authenticated but not authorized |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Duplicate, version conflict |
+| 422 | Unprocessable | Semantic validation failure |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Error | Unexpected server failure |
+
+### Error Handling Best Practices
+- Catch errors at the boundary — global error handler middleware
+- Log errors with context (request ID, user, stack trace)
+- Never expose internal details to clients in production
+- Use custom error classes for business logic errors
+- Return actionable error messages when possible
+
+## Background Processing
+
+### Job Queue Patterns
+- **Laravel Queues** (PHP) — Redis/SQS/database drivers, retries, rate limiting, Horizon dashboard
+- **BullMQ** (Node.js) — Redis-based, reliable, with retry and scheduling
+- **Celery** (Python) — Distributed task queue with multiple brokers
+- **Temporal** — Durable workflow orchestration (any language)
+- **Asynq** (Go) — Simple Redis-based task queue
+
+### Common Use Cases
+- Email sending and notifications
+- Image/video processing
+- Report generation
+- Data imports/exports
+- Webhook delivery with retry
+
+### Best Practices
+- Idempotent jobs — safe to retry on failure
+- Dead letter queue for permanently failed jobs
+- Monitor queue depth and processing latency
+- Set appropriate timeouts and retry limits
+- Log job lifecycle (enqueued, started, completed, failed)
+
+## Technology Recommendations
+
+### By Use Case
+| Use Case | Recommended Stack |
+|----------|-------------------|
+| REST API (TypeScript) | Fastify + Prisma + Redis |
+| REST API (Python) | FastAPI + SQLAlchemy + Redis |
+| REST API (PHP) | Laravel + Eloquent + Redis |
+| Full-stack web (PHP) | Laravel + Livewire or Inertia.js |
+| GraphQL API | NestJS + Apollo + Prisma |
+| Microservice | Go + Gin + gRPC + NATS |
+| Full-stack web (JS) | Next.js API routes or Django |
+| High-performance | Rust + Axum + SQLx |
+| Enterprise (PHP) | Laravel + Horizon + Octane |
+| Enterprise (TS) | NestJS + TypeORM + BullMQ |

package/.opencode/skills/code-quality/SKILL.md

@@ -156,6 +156,14 @@ Sort alphabetically within groups.
 - Use interfaces for abstraction
 - Write table-driven tests
 
+### PHP
+- Follow PSR-12 coding standard
+- Use strict types (`declare(strict_types=1)`)
+- Leverage PHP 8+ features (enums, readonly, named args, match)
+- Use type declarations for params, returns, and properties
+- Follow Laravel conventions (if using Laravel)
+- Use dependency injection over facades in application code
+
 ### Rust
 - Run cargo fmt and clippy
 - Use Result/Option
@@ -208,6 +216,10 @@ Sort alphabetically within groups.
 ### Tools
 - **ESLint** - JavaScript/TypeScript
 - **Prettier** - Multi-language formatter
+- **PHP CS Fixer** - PHP formatter (PSR-12)
+- **Laravel Pint** - Laravel's opinionated PHP formatter (built on CS Fixer)
+- **PHPStan / Larastan** - PHP static analysis (levels 0-9)
+- **Psalm** - PHP static analysis with type inference
 - **Black** - Python formatter
 - **Ruff** - Python linter
 - **gofmt** - Go formatter