gaia-framework 1.57.0 → 1.57.2

package/_gaia/dev/knowledge/typescript/ts-conventions.md

@@ -1,133 +0,0 @@
----
-name: TypeScript Conventions and Standards
-stack: typescript
-version: "1.0"
-focus: [typescript]
----
-
-# TypeScript Conventions and Standards
-
-## Principle
-
-Enable strict mode, use TypeScript's type system expressively (utility types, generics, discriminated unions), organize code with barrel exports and path aliases, and treat types as documentation. Prefer `interface` for object shapes and `type` for unions, intersections, and mapped types.
-
-## Rationale
-
-TypeScript's value comes from its type system catching errors at compile time. Strict mode (`"strict": true`) enables all strictness flags, preventing common bugs like implicit `any`, unchecked nulls, and incorrect `this` binding. Utility types (`Partial`, `Pick`, `Omit`, `Record`) reduce boilerplate. Generics enable reusable, type-safe abstractions. Barrel exports and path aliases create clean public APIs and eliminate deep relative import paths.
-
-## Pattern Examples
-
-### Pattern 1: Strict Mode and Utility Types
-
-```typescript
-// tsconfig.json — strict mode enabled
-// { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }
-
-// Utility types reduce duplication
-interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: 'admin' | 'member' | 'viewer';
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-// Derive types from the source of truth
-type CreateUserInput = Omit<User, 'id' | 'createdAt' | 'updatedAt'>;
-type UpdateUserInput = Partial<Pick<User, 'name' | 'role'>>;
-type UserSummary = Pick<User, 'id' | 'name' | 'email'>;
-
-// Record for typed dictionaries
-type PermissionMap = Record<User['role'], string[]>;
-
-const permissions: PermissionMap = {
-  admin: ['read', 'write', 'delete', 'manage'],
-  member: ['read', 'write'],
-  viewer: ['read'],
-};
-```
-
-### Pattern 2: Generics and Discriminated Unions
-
-```typescript
-// Generic Result type for explicit error handling
-type Result<T, E = Error> =
-  | { success: true; data: T }
-  | { success: false; error: E };
-
-function ok<T>(data: T): Result<T> {
-  return { success: true, data };
-}
-
-function fail<E>(error: E): Result<never, E> {
-  return { success: false, error };
-}
-
-// Usage — compiler forces handling both cases
-async function fetchUser(id: string): Promise<Result<User, string>> {
-  try {
-    const user = await db.users.findUnique({ where: { id } });
-    if (!user) return fail(`User ${id} not found`);
-    return ok(user);
-  } catch (e) {
-    return fail('Database error');
-  }
-}
-
-const result = await fetchUser('123');
-if (result.success) {
-  console.log(result.data.name);  // TypeScript knows data exists
-} else {
-  console.error(result.error);    // TypeScript knows error exists
-}
-
-// Discriminated union for state machines
-type AsyncState<T> =
-  | { status: 'idle' }
-  | { status: 'loading' }
-  | { status: 'success'; data: T }
-  | { status: 'error'; error: Error };
-```
-
-### Pattern 3: Barrel Exports and Path Aliases
-
-```typescript
-// src/features/users/index.ts — barrel export
-export { UserService } from './user.service';
-export { UserRepository } from './user.repository';
-export type { User, CreateUserInput, UpdateUserInput } from './user.types';
-// Do NOT export internal helpers or implementation details
-
-// tsconfig.json paths
-// {
-//   "compilerOptions": {
-//     "baseUrl": ".",
-//     "paths": {
-//       "@/features/*": ["src/features/*"],
-//       "@/shared/*": ["src/shared/*"],
-//       "@/config": ["src/config/index.ts"]
-//     }
-//   }
-// }
-
-// Clean imports from consumers
-import { UserService } from '@/features/users';
-import { Logger } from '@/shared/logging';
-import { config } from '@/config';
-```
-
-## Anti-Patterns
-
-- **`any` escape hatch**: Using `any` to silence type errors defeats TypeScript's purpose. Use `unknown` for truly unknown types, then narrow with type guards.
-- **Type assertions (`as`)**: `response as User` skips type checking. Use type guards or validation (Zod, io-ts) for runtime safety.
-- **Enums for simple unions**: `enum Role { Admin, Member }` is heavier than `type Role = 'admin' | 'member'`. Prefer string literal unions.
-- **Deep relative imports**: `import { X } from '../../../shared/utils/helpers'`. Use path aliases (`@/shared/utils`).
-- **No strict mode**: Running without `"strict": true` allows implicit `any` and unchecked nulls throughout the codebase.
-
-## Integration Points
-
-- **React**: Typed props, hooks, and context use these conventions; see `react-patterns.md`.
-- **Next.js**: Route handlers, page props, and metadata types; see `nextjs-patterns.md`.
-- **Express**: Typed middleware and request extensions; see `express-patterns.md`.
-- **ESLint**: Use `@typescript-eslint/parser` and `@typescript-eslint/eslint-plugin` for TypeScript-aware linting.

package/_gaia/dev/module-help.csv

@@ -1,10 +0,0 @@
-name,code,command,description,agent
-"typescript-dev","agent-dev-typescript","gaia-agent-dev-typescript","TypeScript/React/Next.js/Express developer","Cleo"
-"angular-dev","agent-dev-angular","gaia-agent-dev-angular","Angular/RxJS/NgRx developer","Lena"
-"flutter-dev","agent-dev-flutter","gaia-agent-dev-flutter","Flutter/Dart cross-platform developer","Freya"
-"java-dev","agent-dev-java","gaia-agent-dev-java","Spring Boot/JPA/microservices developer","Hugo"
-"python-dev","agent-dev-python","gaia-agent-dev-python","Django/FastAPI/data pipeline developer","Ravi"
-"mobile-dev","agent-dev-mobile","gaia-agent-dev-mobile","React Native/Swift/Kotlin developer","Talia"
-"dev-story","dev-story","gaia-dev-story","Implement a user story (use with any dev agent)","dev-*"
-"code-review","code-review","gaia-code-review","Perform code review (use with any dev agent)","dev-*"
-"quick-dev","quick-dev","gaia-quick-dev","Implement a quick spec (use with any dev agent)","dev-*"

package/_gaia/dev/skills/_skill-index.yaml

@@ -1,55 +0,0 @@
-skills:
-  - file: git-workflow.md
-    sections:
-      - { id: branching, line_range: [14, 46], description: "Branch naming, trunk-based dev, release branches" }
-      - { id: commits, line_range: [47, 90], description: "Conventional commit format, types, scopes" }
-      - { id: pull-requests, line_range: [91, 126], description: "PR template, review checklist, merge strategies" }
-      - { id: conflict-resolution, line_range: [127, 157], description: "Merge vs rebase, conflict markers, resolution" }
-
-  - file: api-design.md
-    sections:
-      - { id: rest-conventions, line_range: [14, 63], description: "REST naming, HTTP methods, status codes" }
-      - { id: graphql, line_range: [64, 104], description: "GraphQL schema design, queries, mutations" }
-      - { id: openapi, line_range: [105, 156], description: "OpenAPI specification, documentation" }
-      - { id: versioning, line_range: [157, 194], description: "API versioning strategies" }
-      - { id: error-standards, line_range: [195, 229], description: "RFC 7807 error responses" }
-
-  - file: database-design.md
-    sections:
-      - { id: schema-design, line_range: [14, 51], description: "Naming conventions, normalization" }
-      - { id: migrations, line_range: [52, 99], description: "Forward-only migration strategies" }
-      - { id: indexing, line_range: [100, 131], description: "Index optimization, covering indexes" }
-      - { id: orm-patterns, line_range: [132, 172], description: "N+1 prevention, ORM best practices" }
-
-  - file: docker-workflow.md
-    sections:
-      - { id: multi-stage-builds, line_range: [14, 93], description: "Multi-stage Dockerfile patterns" }
-      - { id: compose, line_range: [94, 157], description: "Docker Compose for development" }
-      - { id: security-scanning, line_range: [158, 222], description: "Image scanning, secrets handling" }
-
-  - file: testing-patterns.md
-    sections:
-      - { id: tdd-cycle, line_range: [14, 51], description: "Red-green-refactor cycle" }
-      - { id: unit-testing, line_range: [52, 102], description: "Unit test structure (AAA), test pyramid" }
-      - { id: integration-testing, line_range: [103, 170], description: "Integration test patterns" }
-      - { id: test-doubles, line_range: [171, 232], description: "Mock, stub, spy, fake strategies" }
-
-  - file: code-review-standards.md
-    sections:
-      - { id: review-checklist, line_range: [14, 59], description: "Universal code review checklist" }
-      - { id: solid-principles, line_range: [60, 132], description: "SOLID violation detection" }
-      - { id: complexity-metrics, line_range: [133, 226], description: "Cyclomatic and cognitive complexity" }
-
-  - file: documentation-standards.md
-    sections:
-      - { id: readme-template, line_range: [14, 81], description: "README structure and sections" }
-      - { id: adr-format, line_range: [82, 144], description: "Architecture Decision Record template" }
-      - { id: inline-comments, line_range: [145, 196], description: "When and how to comment code" }
-      - { id: api-docs, line_range: [197, 256], description: "API documentation conventions" }
-
-  - file: security-basics.md
-    sections:
-      - { id: owasp-top-10, line_range: [14, 68], description: "OWASP Top 10 prevention patterns" }
-      - { id: input-validation, line_range: [69, 118], description: "Validation at system boundaries" }
-      - { id: secrets-management, line_range: [119, 166], description: "Environment-based secrets" }
-      - { id: cors-csrf, line_range: [167, 230], description: "CORS and CSRF configuration, protection" }

package/_gaia/dev/skills/api-design.md

@@ -1,229 +0,0 @@
----
-name: api-design
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: REST endpoint naming
-    expected: Resource names are plural nouns, lowercase, hyphenated
-  - scenario: Error response format
-    expected: Response follows RFC 7807 problem details structure
-  - scenario: API versioning
-    expected: Version strategy is documented and consistently applied
----
-
-<!-- SECTION: rest-conventions -->
-## REST Conventions
-
-### Resource Naming
-- Use plural nouns: `/users`, `/orders`, `/products`
-- Use lowercase with hyphens: `/order-items`, `/user-profiles`
-- Nest for relationships: `/users/{id}/orders`
-- Max 3 levels of nesting; beyond that, use query params or separate resources
-- No verbs in URLs (use HTTP methods instead)
-
-### HTTP Methods
-| Method | Use | Idempotent | Safe |
-|--------|-----|------------|------|
-| GET | Retrieve resource(s) | Yes | Yes |
-| POST | Create resource | No | No |
-| PUT | Full update/replace | Yes | No |
-| PATCH | Partial update | No | No |
-| DELETE | Remove resource | Yes | No |
-
-### Status Codes
-| Code | Meaning | Use When |
-|------|---------|----------|
-| 200 | OK | Successful GET, PUT, PATCH |
-| 201 | Created | Successful POST creating resource |
-| 204 | No Content | Successful DELETE |
-| 400 | Bad Request | Invalid input/validation failure |
-| 401 | Unauthorized | Missing or invalid authentication |
-| 403 | Forbidden | Authenticated but not authorized |
-| 404 | Not Found | Resource does not exist |
-| 409 | Conflict | Duplicate resource or state conflict |
-| 422 | Unprocessable | Valid syntax but semantic error |
-| 429 | Too Many Requests | Rate limit exceeded |
-| 500 | Server Error | Unexpected server failure |
-
-### Pagination
-```json
-{
-  "data": [...],
-  "pagination": {
-    "page": 1,
-    "per_page": 20,
-    "total": 150,
-    "total_pages": 8
-  }
-}
-```
-- Use `?page=1&per_page=20` for offset pagination
-- Use `?cursor=abc123&limit=20` for cursor pagination (preferred for large datasets)
-- Always include pagination metadata in response
-
-<!-- SECTION: graphql -->
-## GraphQL Design
-
-### Schema Design
-- Use descriptive type names: `User`, `OrderItem`, `PaymentMethod`
-- Prefer input types for mutations: `input CreateUserInput { ... }`
-- Use enums for fixed value sets: `enum OrderStatus { PENDING, SHIPPED, DELIVERED }`
-- Add descriptions to all types and fields
-
-### Query and Mutation Patterns
-```graphql
-type Query {
-  user(id: ID!): User
-  users(filter: UserFilter, pagination: PaginationInput): UserConnection!
-}
-
-type Mutation {
-  createUser(input: CreateUserInput!): CreateUserPayload!
-  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
-}
-
-type CreateUserPayload {
-  user: User
-  errors: [UserError!]!
-}
-```
-- Return payload types from mutations (not raw entities)
-- Include an `errors` field in payloads for domain-level errors
-- Use Relay-style connections for paginated lists
-
-### Resolvers
-- Keep resolvers thin -- delegate to service layer
-- Use DataLoader for batching to prevent N+1 queries
-- Return typed errors, not generic messages
-
-### Subscriptions
-- Use for real-time updates only (chat, notifications, live data)
-- Prefer polling for infrequently changing data
-- Always implement authentication on subscription connections
-- Handle connection lifecycle (connect, disconnect, reconnect)
-
-<!-- SECTION: openapi -->
-## OpenAPI Specification
-
-### Spec Structure
-```yaml
-openapi: 3.0.3
-info:
-  title: API Name
-  version: 1.0.0
-  description: Brief API description
-paths:
-  /resources:
-    get:
-      summary: List resources
-      operationId: listResources
-      tags: [resources]
-      parameters:
-        - name: page
-          in: query
-          schema:
-            type: integer
-            default: 1
-      responses:
-        '200':
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/ResourceList'
-        '401':
-          $ref: '#/components/responses/Unauthorized'
-components:
-  schemas: {}
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-```
-
-### Best Practices
-- Every endpoint needs `operationId`, `summary`, `tags`
-- Use `$ref` for shared schemas -- never inline complex types
-- Document all possible response codes per endpoint
-- Include request/response examples for non-trivial endpoints
-
-### Code Generation
-- Generate server stubs from spec (spec-first development)
-- Generate client SDKs for frontend consumers
-- Validate requests/responses against spec in tests
-- Keep spec in sync with implementation via CI checks
-
-<!-- SECTION: versioning -->
-## API Versioning
-
-### URL Versioning (Recommended)
-```
-/api/v1/users
-/api/v2/users
-```
-- Simple, explicit, visible in logs and documentation
-- Easy to route at load balancer level
-
-### Header Versioning (Alternative)
-```
-Accept: application/vnd.api+json;version=2
-```
-- Cleaner URLs but harder to test in browser
-- Requires custom middleware to parse
-
-### Breaking vs Non-Breaking Changes
-A change is **breaking** if it:
-- Removes or renames a field
-- Changes a field's type
-- Adds a required field to a request body
-- Changes authentication mechanism
-- Changes error response format
-
-A change is **non-breaking** if it:
-- Adds an optional field to request or response
-- Adds a new endpoint
-- Adds a new optional query parameter
-
-### Deprecation Policy
-1. Announce deprecation with timeline (minimum 6 months)
-2. Add `Sunset` header: `Sunset: Sat, 01 Jan 2027 00:00:00 GMT`
-3. Add `Deprecation` header: `Deprecation: true`
-4. Log usage of deprecated endpoints for migration tracking
-5. Remove only after sunset date passes
-
-<!-- SECTION: error-standards -->
-## Error Standards (RFC 7807)
-
-### Problem Details Structure
-```json
-{
-  "type": "https://api.example.com/errors/validation-error",
-  "title": "Validation Error",
-  "status": 422,
-  "detail": "The 'email' field must be a valid email address.",
-  "instance": "/users/registration",
-  "trace_id": "req-abc-123-def",
-  "errors": [
-    {
-      "field": "email",
-      "message": "Must be a valid email address",
-      "code": "INVALID_FORMAT"
-    }
-  ]
-}
-```
-
-### Error Codes
-- Use machine-readable error codes: `INVALID_FORMAT`, `NOT_FOUND`, `RATE_LIMITED`
-- Document all error codes in API reference
-- Keep codes stable across API versions
-- Group by category: `AUTH_*`, `VALIDATION_*`, `RESOURCE_*`
-
-### Error Handling Rules
-- Never expose stack traces in production
-- Log full error details server-side with correlation ID
-- Return consistent error format across all endpoints
-- Include `trace_id` for debugging and support requests
-- Localize `detail` field using `Accept-Language` header when needed
-- Error codes remain stable across locales

package/_gaia/dev/skills/code-review-standards.md

@@ -1,226 +0,0 @@
----
-name: code-review-standards
-version: '1.0'
-applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
-test_scenarios:
-  - scenario: Review checklist application
-    expected: All checklist items are evaluated and blocking issues are flagged
-  - scenario: SOLID violation detection
-    expected: Reviewer identifies specific SOLID principle violations with remediation suggestions
-  - scenario: Complexity assessment
-    expected: Functions exceeding complexity thresholds are flagged with refactoring recommendations
----
-
-<!-- SECTION: review-checklist -->
-## Review Checklist
-
-### Correctness
-- [ ] Code does what the PR description claims
-- [ ] Edge cases are handled (null, empty, boundary values)
-- [ ] Error paths are handled gracefully (no swallowed exceptions)
-- [ ] No off-by-one errors in loops or slicing
-- [ ] Concurrent access is safe (if applicable)
-
-### Security
-- [ ] No secrets, credentials, or API keys in code
-- [ ] User input is validated and sanitized
-- [ ] SQL queries use parameterized statements
-- [ ] Authentication and authorization are enforced
-- [ ] Sensitive data is not logged
-
-### Performance
-- [ ] No N+1 query patterns
-- [ ] No unnecessary re-renders in UI components
-- [ ] Large collections use pagination
-- [ ] Expensive operations are cached or deferred
-- [ ] Database queries have appropriate indexes
-
-### Maintainability
-- [ ] Functions and methods are under 30 lines
-- [ ] Classes have a single responsibility
-- [ ] Variable and function names are descriptive
-- [ ] No commented-out code
-- [ ] No magic numbers (use named constants)
-- [ ] DRY: no copy-pasted logic blocks
-
-### Testing
-- [ ] New code has corresponding tests
-- [ ] Tests cover happy path and error cases
-- [ ] Tests are independent and repeatable
-- [ ] No test code in production builds
-- [ ] Mocks are reset between tests
-
-### Review Etiquette
-- Comment on the code, not the person
-- Suggest, do not demand: "Consider using X because..."
-- Distinguish blocking issues from suggestions
-- Approve with minor comments when appropriate
-- Respond to reviews within one business day
-
-<!-- SECTION: solid-principles -->
-## SOLID Principles
-
-### Single Responsibility (SRP)
-A class should have only one reason to change.
-
-**Violation signal**: Class has methods for unrelated concerns.
-```typescript
-// BAD: UserService handles auth, email, and data access
-class UserService {
-  authenticate(credentials) { ... }
-  sendWelcomeEmail(user) { ... }
-  saveToDatabase(user) { ... }
-}
-
-// GOOD: Separated responsibilities
-class AuthService { authenticate(credentials) { ... } }
-class EmailService { sendWelcome(user) { ... } }
-class UserRepository { save(user) { ... } }
-```
-
-### Open/Closed (OCP)
-Open for extension, closed for modification.
-
-**Violation signal**: Adding a feature requires modifying existing switch/if chains.
-```typescript
-// BAD: Must modify function for each new type
-function calculateArea(shape) {
-  if (shape.type === 'circle') return Math.PI * shape.radius ** 2;
-  if (shape.type === 'rect') return shape.width * shape.height;
-  // Must add more conditions for new shapes
-}
-
-// GOOD: Extend via polymorphism
-interface Shape { area(): number; }
-class Circle implements Shape { area() { return Math.PI * this.radius ** 2; } }
-class Rectangle implements Shape { area() { return this.width * this.height; } }
-```
-
-### Liskov Substitution (LSP)
-Subtypes must be substitutable for their base types.
-
-**Violation signal**: Subclass overrides a method to throw or do nothing.
-
-### Interface Segregation (ISP)
-No client should depend on methods it does not use.
-
-**Violation signal**: Interface has many methods and implementations leave some as no-ops.
-
-### Dependency Inversion (DIP)
-Depend on abstractions, not concretions.
-
-**Violation signal**: Classes instantiate their own dependencies with `new`.
-```typescript
-// BAD: Tightly coupled to concrete class
-class OrderService {
-  private repo = new PostgresOrderRepository();
-}
-
-// GOOD: Depend on abstraction, inject at construction
-class OrderService {
-  constructor(private repo: OrderRepository) {}
-}
-```
-
-### Review Flags
-When reviewing, flag SOLID violations with a prefix tag:
-```
-[SRP] This class handles both X and Y -- consider splitting.
-[OCP] Adding new types requires modifying this switch -- consider strategy pattern.
-[DIP] Direct dependency on concrete class -- inject via interface.
-```
-
-<!-- SECTION: complexity-metrics -->
-## Complexity Metrics
-
-### Cyclomatic Complexity
-Measures the number of independent paths through a function.
-
-**Calculation**: Count decision points + 1
-- Each `if`, `else if`, `case`, `while`, `for`, `&&`, `||`, `catch` adds 1
-
-| Score | Risk Level | Action |
-|-------|------------|--------|
-| 1-5 | Low | Acceptable |
-| 6-10 | Moderate | Review for simplification |
-| 11-20 | High | Refactor required |
-| 21+ | Critical | Must be broken apart |
-
-### Cognitive Complexity
-Measures how hard code is to understand (more nuanced than cyclomatic).
-
-Increases with:
-- Nesting depth (penalty compounds with each level)
-- Breaks in linear flow (else, catch, continue, break)
-- Recursion
-
-```typescript
-// Cognitive complexity: 7 (nested conditions compound)
-function getLabel(user, order) {       // +0
-  if (user.isAdmin) {                  // +1
-    if (order.isPriority) {            // +2 (nesting)
-      return 'admin-priority';
-    } else {                           // +1
-      return 'admin-standard';
-    }
-  } else if (user.isVip) {            // +1
-    return 'vip';
-  } else {                            // +1
-    if (order.total > 100) {           // +2 (nesting)
-      return 'high-value';
-    }
-    return 'standard';
-  }
-}
-```
-
-### Refactoring High-Complexity Code
-**Extract method**: Pull branches into well-named functions.
-```typescript
-// Before: one long function with nested conditions
-function processOrder(order) {
-  // 40 lines with nested if/else
-}
-
-// After: decomposed into focused functions
-function processOrder(order) {
-  const pricing = calculatePricing(order);
-  const shipping = determineShipping(order);
-  return finalizeOrder(order, pricing, shipping);
-}
-```
-
-**Replace conditionals with polymorphism**: When branching on type, use strategy pattern.
-
-**Use early returns**: Flatten nested conditions with guard clauses.
-```typescript
-// Before: deeply nested
-function validate(input) {
-  if (input) {
-    if (input.name) {
-      if (input.name.length > 0) {
-        return true;
-      }
-    }
-  }
-  return false;
-}
-
-// After: guard clauses
-function validate(input) {
-  if (!input) return false;
-  if (!input.name) return false;
-  if (input.name.length === 0) return false;
-  return true;
-}
-```
-
-### Thresholds for Code Review
-| Metric | Threshold | Action |
-|--------|-----------|--------|
-| Function length | > 30 lines | Suggest extraction |
-| Cyclomatic complexity | > 10 | Require refactoring |
-| Cognitive complexity | > 15 | Require refactoring |
-| Parameter count | > 4 | Suggest object parameter |
-| Nesting depth | > 3 levels | Require flattening |
-| Class methods | > 10 public | Suggest decomposition |