antigravity-ai-kit 3.2.0 → 3.3.1

package/.agent/skills/architecture/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: architecture
-description: System design patterns and architectural principles
+description: "System design patterns, DDD, 12-Factor App, SOLID principles, event-driven architecture, and architectural decision frameworks"
 triggers: [context, architecture, design, system]
 ---
 
 # Architecture Skill
 
-> **Purpose**: Apply proven architectural patterns for scalable systems
+> **Purpose**: Apply proven architectural patterns for scalable, maintainable systems using industry-standard methodologies
 
 ---
 
 ## Overview
 
-This skill provides guidance for designing maintainable, scalable software architectures using industry-standard patterns.
+This skill provides deep guidance for designing software architectures using Domain-Driven Design, Clean Architecture, the 12-Factor App methodology, event-driven patterns, and SOLID principles.
 
 ---
 
@@ -22,88 +22,209 @@ This skill provides guidance for designing maintainable, scalable software archi
 
 ```
 ┌─────────────────────────┐
-│    Presentation Layer   │  ← Controllers, Views
+│    Presentation Layer   │  ← Controllers, Views, API endpoints
 ├─────────────────────────┤
-│    Application Layer    │  ← Use Cases, Services
+│    Application Layer    │  ← Use Cases, Services, Orchestration
 ├─────────────────────────┤
-│      Domain Layer       │  ← Entities, Business Logic
+│      Domain Layer       │  ← Entities, Business Logic, Domain Events
 ├─────────────────────────┤
-│   Infrastructure Layer  │  ← Database, External APIs
+│   Infrastructure Layer  │  ← Database, External APIs, Messaging
 └─────────────────────────┘
 ```
 
+**Rule**: Each layer ONLY imports from the layer directly below it. Never skip layers.
+
 ### 2. Clean Architecture
 
-- **Entities**: Core business objects
-- **Use Cases**: Application-specific business rules
-- **Interface Adapters**: Controllers, Presenters, Gateways
-- **Frameworks**: External concerns (DB, Web, Devices)
+```
+                ┌─────────────┐
+                │  Frameworks  │  ← Web, DB, UI (outermost)
+              ┌─┤             ├─┐
+              │ │  Adapters   │ │  ← Controllers, Gateways, Presenters
+            ┌─┤ │             │ ├─┐
+            │ │ │  Use Cases  │ │ │  ← Application business rules
+          ┌─┤ │ │             │ │ ├─┐
+          │ │ │ │  Entities   │ │ │ │  ← Core business objects (innermost)
+          └─┤ │ │             │ │ ├─┘
+            └─┤ │             │ ├─┘
+              └─┤             ├─┘
+                └─────────────┘
+```
+
+**Dependency Rule**: Source code dependencies ALWAYS point inward. Inner layers know nothing about outer layers.
 
 ### 3. Hexagonal Architecture (Ports & Adapters)
 
 ```
          ┌─────────────────┐
    ──────│     Ports       │──────
-         │   (Interfaces)  │
-         │                 │
+   Input │   (Interfaces)  │ Output
+   Ports │                 │ Ports
          │  Domain Core    │
          │                 │
    ──────│    Adapters     │──────
+   Input │  (Implementations)│ Output
+   Adapters                  Adapters
          └─────────────────┘
 ```
 
+**Key Insight**: The domain core defines ports (interfaces). Adapters implement them. This makes the domain testable without infrastructure.
+
+---
+
+## Domain-Driven Design (DDD)
+
+### Strategic DDD — Bounded Contexts
+
+| Concept | Definition | Example |
+|:--------|:-----------|:--------|
+| **Bounded Context** | A boundary within which a domain model is consistent | "Order" means different things in Sales vs Shipping |
+| **Ubiquitous Language** | Shared vocabulary within a bounded context | "Customer" in Sales = "Recipient" in Shipping |
+| **Context Map** | Visual map of relationships between bounded contexts | Sales ← Customer/Supplier → Fulfillment |
+| **Anti-Corruption Layer** | Translation layer between contexts with different models | Adapter that maps external API models to domain models |
+
+### Tactical DDD — Building Blocks
+
+| Building Block | Purpose | Rules |
+|:--------------|:--------|:------|
+| **Entity** | Object with identity that persists over time | Has unique ID, mutable state, lifecycle |
+| **Value Object** | Immutable object defined by its attributes | No ID, compared by value, always valid |
+| **Aggregate** | Cluster of entities with a root that enforces invariants | External access only through root, transactional consistency |
+| **Repository** | Interface for aggregate persistence | One per aggregate, hides storage details |
+| **Domain Service** | Stateless logic spanning multiple aggregates | When logic doesn't belong to a single entity |
+| **Domain Event** | Record of something that happened in the domain | Immutable, past tense (OrderPlaced, PaymentReceived) |
+| **Factory** | Complex object/aggregate creation | Encapsulates creation logic and invariant enforcement |
+
+### Aggregate Design Rules
+
+1. **Protect invariants within aggregate boundaries** — All business rules enforced by the aggregate root
+2. **Reference other aggregates by ID only** — Never hold direct object references across aggregate boundaries
+3. **One transaction per aggregate** — Don't modify multiple aggregates in a single transaction
+4. **Design small aggregates** — Smaller = less contention, better scalability
+5. **Use eventual consistency between aggregates** — Domain events for cross-aggregate communication
+
+---
+
+## 12-Factor App Methodology
+
+| Factor | Principle | Implementation |
+|:-------|:----------|:--------------|
+| **I. Codebase** | One codebase tracked in VCS, many deploys | Git repo, branches for environments |
+| **II. Dependencies** | Explicitly declare and isolate dependencies | `package.json` + lockfile, no global installs |
+| **III. Config** | Store config in the environment | `process.env.*`, never in code |
+| **IV. Backing Services** | Treat backing services as attached resources | Database URL as environment variable |
+| **V. Build, Release, Run** | Strictly separate build and run stages | CI builds artifact → deploy artifact → run |
+| **VI. Processes** | Execute the app as stateless processes | No sticky sessions, no in-memory state between requests |
+| **VII. Port Binding** | Export services via port binding | `app.listen(PORT)`, no container-specific coupling |
+| **VIII. Concurrency** | Scale out via the process model | Horizontal scaling, not bigger machines |
+| **IX. Disposability** | Maximize robustness with fast startup and graceful shutdown | `SIGTERM` handler, connection draining |
+| **X. Dev/Prod Parity** | Keep development, staging, and production as similar as possible | Same database, same services, Docker |
+| **XI. Logs** | Treat logs as event streams | Write to stdout, let platform aggregate |
+| **XII. Admin Processes** | Run admin/management tasks as one-off processes | Database migrations, data fixes as scripts |
+
+---
+
+## Event-Driven Architecture
+
+### Pattern Selection
+
+| Pattern | Use When | Complexity | Consistency |
+|:--------|:---------|:-----------|:-----------|
+| **Request/Response** | Synchronous, simple operations | Low | Strong |
+| **Event Notification** | Inform other services something happened | Low | Eventual |
+| **Event-Carried State Transfer** | Share data without coupling to source | Medium | Eventual |
+| **Event Sourcing** | Full audit trail, state reconstruction | High | Strong (per aggregate) |
+| **CQRS** | Different read/write models needed | Medium-High | Eventual (between models) |
+
+### Event Design Principles
+
+1. **Events are facts** — Something that happened (past tense: `OrderPlaced`, not `PlaceOrder`)
+2. **Events are immutable** — Never modify or delete events
+3. **Events carry sufficient data** — Include everything consumers need (avoid callbacks)
+4. **Events have schemas** — Version and validate event structures
+5. **Events are ordered within an aggregate** — Global ordering is optional and expensive
+
 ---
 
 ## Design Principles
 
-### SOLID
+### SOLID — Applied
 
-| Principle                 | Description                                 |
-| :------------------------ | :------------------------------------------ |
-| **S**ingle Responsibility | One reason to change                        |
-| **O**pen/Closed           | Open for extension, closed for modification |
-| **L**iskov Substitution   | Subtypes must be substitutable              |
-| **I**nterface Segregation | Many specific interfaces                    |
-| **D**ependency Inversion  | Depend on abstractions                      |
+| Principle | Description | Violation Smell | Fix |
+|:----------|:-----------|:---------------|:----|
+| **S**ingle Responsibility | One reason to change | Class does file I/O AND business logic | Split into Repository + Service |
+| **O**pen/Closed | Open for extension, closed for modification | `if/else` chain for new types | Strategy pattern, polymorphism |
+| **L**iskov Substitution | Subtypes must be substitutable | Subclass throws unexpected exception | Respect base class contract |
+| **I**nterface Segregation | Many specific interfaces | God interface with 20 methods | Split into focused interfaces |
+| **D**ependency Inversion | Depend on abstractions | Service directly imports Prisma client | Inject Repository interface |
 
-### DRY, KISS, YAGNI
+### Additional Principles
 
-- **DRY**: Don't Repeat Yourself
-- **KISS**: Keep It Simple, Stupid
-- **YAGNI**: You Aren't Gonna Need It
+- **DRY**: Don't Repeat Yourself — Extract shared logic, but avoid premature abstraction
+- **KISS**: Keep It Simple — Prefer straightforward solutions over clever ones
+- **YAGNI**: You Aren't Gonna Need It — Don't build for hypothetical future requirements
 
 ---
 
-## Module Structure
+## Module Structure (DDD-Aligned)
 
 ```
 src/
-├── domain/               # Core business logic
-│   ├── entities/
-│   ├── value-objects/
-│   └── services/
-├── application/          # Use cases
-│   ├── commands/
-│   ├── queries/
-│   └── handlers/
-├── infrastructure/       # External concerns
-│   ├── database/
-│   ├── messaging/
-│   └── external-apis/
-└── interfaces/           # Entry points
-    ├── http/
-    ├── graphql/
-    └── cli/
+├── domain/               # Core business logic (no framework imports)
+│   ├── entities/         # Entities with identity
+│   ├── value-objects/    # Immutable value types
+│   ├── events/           # Domain events
+│   ├── services/         # Domain services
+│   └── repositories/     # Repository interfaces (ports)
+├── application/          # Use cases / application services
+│   ├── commands/         # Write operations
+│   ├── queries/          # Read operations
+│   └── handlers/         # Command/query handlers
+├── infrastructure/       # External concerns (adapters)
+│   ├── database/         # Repository implementations
+│   ├── messaging/        # Event bus, message queues
+│   ├── external-apis/    # Third-party integrations
+│   └── config/           # Environment configuration
+└── interfaces/           # Entry points (driving adapters)
+    ├── http/             # REST/GraphQL controllers
+    ├── events/           # Event consumers
+    └── cli/              # CLI commands
+```
+
+---
+
+## Architecture Decision Records (ADRs)
+
+### When to Write an ADR
+
+- Choosing between architectural approaches (monolith vs microservices)
+- Selecting a technology (PostgreSQL vs MongoDB)
+- Establishing a pattern (event sourcing vs CRUD)
+- Making a trade-off (consistency vs availability)
+
+### ADR Template
+
+```markdown
+# ADR-NNN: [Decision Title]
+
+**Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+**Date**: YYYY-MM-DD
+**Context**: [What is the issue? What constraints exist?]
+**Decision**: [What was decided?]
+**Consequences**: [What are the trade-offs? What becomes easier/harder?]
+**Alternatives Considered**: [What was rejected and why?]
 ```
 
 ---
 
 ## Quick Reference
 
-| Pattern       | When to Use                      |
-| :------------ | :------------------------------- |
-| Monolith      | MVP, small team                  |
-| Microservices | Scale, team autonomy             |
-| Event-Driven  | Async, decoupling                |
-| CQRS          | Read/write separation            |
-| Serverless    | Variable load, cost optimization |
+| Pattern | When to Use |
+|:--------|:-----------|
+| Monolith | MVP, small team, simple domain |
+| Modular Monolith | Growing team, clear bounded contexts, not ready for distributed |
+| Microservices | Large team, independent scaling, domain maturity |
+| Event-Driven | Async workflows, decoupling, audit requirements |
+| CQRS | Different read/write patterns, high-traffic reads |
+| Serverless | Variable load, cost optimization, simple functions |
+| Event Sourcing | Audit trail, state reconstruction, complex domain |

package/.agent/skills/database-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: database-design
-description: Database schema design and optimization patterns
+description: Database schema design, optimization patterns, distributed system consistency models, and zero-downtime migration strategies
 triggers: [context, database, schema, sql, prisma]
 ---
 
@@ -123,13 +123,13 @@ model User {
 ## Query Optimization
 
 ```typescript
-// ❌ N+1 Problem
+// N+1 Problem
 const users = await prisma.user.findMany();
 for (const user of users) {
   const orders = await prisma.order.findMany({ where: { userId: user.id } });
 }
 
-// ✅ Eager Loading
+// Eager Loading
 const users = await prisma.user.findMany({
   include: { orders: true },
 });
@@ -137,6 +137,155 @@ const users = await prisma.user.findMany({
 
 ---
 
+## CAP Theorem
+
+In a distributed system, you can guarantee at most two of three properties simultaneously:
+
+- **Consistency (C)**: Every read returns the most recent write
+- **Availability (A)**: Every request receives a response (no timeout)
+- **Partition Tolerance (P)**: The system continues operating despite network partitions
+
+Since network partitions are unavoidable in distributed systems, the real choice is between CP and AP.
+
+### Decision Matrix
+
+| Trade-off | Guarantees | Sacrifices | When to Choose | Example Systems |
+| :--- | :--- | :--- | :--- | :--- |
+| **CP** | Consistency + Partition Tolerance | Availability during partitions | Financial transactions, inventory counts, leader election | MongoDB (default), HBase, Zookeeper |
+| **AP** | Availability + Partition Tolerance | Consistency (eventual) | Social feeds, caching layers, DNS, session stores | Cassandra, DynamoDB, CouchDB |
+| **CA** | Consistency + Availability | Partition Tolerance | Single-node deployments only (no true distribution) | Traditional RDBMS (PostgreSQL, MySQL single-node) |
+
+---
+
+## ACID vs BASE
+
+### Property Comparison
+
+| Property | ACID | BASE |
+| :--- | :--- | :--- |
+| **Full name** | Atomicity, Consistency, Isolation, Durability | Basically Available, Soft state, Eventually consistent |
+| **Consistency** | Strong (immediate) | Eventual |
+| **Availability** | May block under contention | Prioritizes availability |
+| **Transactions** | Full multi-statement transactions | Single-record atomic ops; app-level sagas |
+| **Scaling** | Vertical first; horizontal is complex | Horizontal by design |
+| **Best for** | Financial systems, booking, inventory | Analytics, social, IoT, content delivery |
+
+### When to Use Each
+
+- **ACID**: Money movement, order processing, anything requiring rollback guarantees, regulatory compliance
+- **BASE**: High-throughput writes, geographically distributed reads, systems where stale reads are acceptable for seconds
+
+---
+
+## Consistency Models
+
+From strongest to weakest, choose the level your application actually needs:
+
+| Model | Guarantee | Latency Cost | Use Case |
+| :--- | :--- | :--- | :--- |
+| **Strict / Linearizable** | Reads always see the latest write globally | Highest (cross-region coordination) | Distributed locks, leader election |
+| **Sequential** | All nodes see operations in the same order | High | Replicated state machines |
+| **Causal** | Causally related operations are seen in order | Medium | Chat applications, collaborative editing |
+| **Read-your-writes** | A client always sees its own writes | Low-Medium | User profile updates, shopping carts |
+| **Monotonic reads** | Once a value is seen, older values are never returned | Low | Dashboard displays, reporting |
+| **Eventual** | All replicas converge given enough time | Lowest | DNS, CDN caches, social media likes |
+
+Choose the weakest model your application can tolerate to maximize performance and availability.
+
+---
+
+## Migration Safety
+
+### Zero-Downtime Migration Pattern
+
+Safe migrations follow a multi-phase approach that avoids locking tables or breaking running application code.
+
+**Phase 1 - Expand**: Add new structures alongside old ones
+**Phase 2 - Migrate**: Backfill data, dual-write to both structures
+**Phase 3 - Contract**: Remove old structures after all consumers have switched
+
+### Safe vs Unsafe Operations
+
+| Operation | Safe? | Zero-Downtime Alternative |
+| :--- | :--- | :--- |
+| **Add nullable column** | Safe | N/A (already safe) |
+| **Add column with default** | Safe (Postgres 11+) | For older versions, add nullable then backfill |
+| **Drop column** | Unsafe | Stop reading column in code first, then drop in next deploy |
+| **Rename column** | Unsafe | Add new column, dual-write, migrate reads, drop old |
+| **Change column type** | Unsafe | Add new column with new type, backfill, swap reads |
+| **Add NOT NULL constraint** | Unsafe | Add CHECK constraint as NOT VALID, then VALIDATE separately |
+| **Add index** | Unsafe (locks table) | Use `CREATE INDEX CONCURRENTLY` (Postgres) |
+| **Drop table** | Unsafe | Remove all references in code first, then drop |
+
+### Backfill Pattern
+
+```typescript
+// Backfill in batches to avoid long-running transactions
+async function backfillNewColumn(batchSize = 1000) {
+  let processed = 0;
+  let hasMore = true;
+
+  while (hasMore) {
+    const rows = await prisma.$executeRaw`
+      UPDATE users
+      SET display_name = first_name || ' ' || last_name
+      WHERE display_name IS NULL
+      LIMIT ${batchSize}
+    `;
+
+    processed += rows;
+    hasMore = rows === batchSize;
+
+    // Yield to other operations between batches
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  return processed;
+}
+```
+
+---
+
+## Connection Pooling
+
+### Pool Size Guidance
+
+| Environment | Pool Size | Rationale |
+| :--- | :--- | :--- |
+| **Development** | 2-5 | Single developer, minimal concurrency |
+| **Production (server)** | 10-20 per instance | Balance between concurrency and DB connection limits |
+| **Production (serverless)** | 1-2 per function | Functions scale horizontally; too many connections exhaust DB limits |
+| **Staging / CI** | 3-5 | Mirrors production behavior without resource waste |
+
+### Sizing Formula
+
+```
+max_pool_size = (db_max_connections - reserved_superuser_connections) / number_of_app_instances
+```
+
+For PostgreSQL with `max_connections = 100`, 3 superuser slots reserved, and 4 app instances:
+`(100 - 3) / 4 = ~24 connections per instance`
+
+### Tool Recommendations
+
+| Tool | Best For | Notes |
+| :--- | :--- | :--- |
+| **PgBouncer** | External pooler for PostgreSQL | Transaction-mode pooling for serverless; sits between app and DB |
+| **Prisma built-in pool** | Prisma ORM users | Configure via `connection_limit` in datasource URL |
+| **Prisma Accelerate** | Serverless / edge | Managed connection pooling with global caching |
+| **RDS Proxy** | AWS deployments | Managed pooler; supports IAM auth and failover |
+| **Supabase Supavisor** | Supabase projects | Built-in pooler with transaction and session modes |
+
+```prisma
+// Prisma connection pool configuration
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL") // ?connection_limit=20&pool_timeout=10
+}
+```
+
+---
+
 ## Quick Reference
 
 | Pattern        | Usage               |
@@ -147,3 +296,8 @@ const users = await prisma.user.findMany({
 | Timestamps     | Always include      |
 | Indexes        | Frequent queries    |
 | Constraints    | Data integrity      |
+| CAP trade-off  | Distributed design  |
+| ACID           | Transactional data  |
+| BASE           | High-scale writes   |
+| Migrations     | Zero-downtime deploys |
+| Connection Pool | Right-size per env |