antigravity-ai-kit 3.2.0 → 3.4.0

package/.agent/rules/architecture.md

@@ -0,0 +1,111 @@
+# Architecture Rules
+
+> **Priority**: HIGH — Enforced in design reviews
+> **Scope**: All workspaces — universal architectural constraints
+
+---
+
+## Architecture Principles
+
+| Principle                | Enforcement                                                   |
+| :----------------------- | :------------------------------------------------------------ |
+| Separation of Concerns   | Each module has a single, well-defined responsibility         |
+| Dependency Direction     | Dependencies ALWAYS point inward — domain never imports infra |
+| Contract-First Design    | Define API contracts before implementation begins             |
+| Explicit Over Implicit   | Configuration, dependencies, and boundaries must be explicit  |
+| Composition Over Inherit | Prefer composition and dependency injection over inheritance  |
+
+---
+
+## Boundary Enforcement
+
+- **NEVER** import backend code from frontend or vice versa
+- **NEVER** skip architectural layers — each layer imports only from the layer directly below
+- **NEVER** hold direct object references across aggregate or module boundaries — use IDs
+- Shared types and contracts are defined at the API boundary and replicated per consumer
+- Cross-module communication uses events or explicit service interfaces, not direct coupling
+
+---
+
+## Project Structure
+
+Projects should follow one of these organizational patterns:
+
+| Pattern          | When to Use                                              |
+| :--------------- | :------------------------------------------------------- |
+| **Monorepo**     | Multiple apps sharing code (Turborepo, Nx, Rush)         |
+| **Polyrepo**     | Independent services with separate lifecycles            |
+| **Modular Mono** | Single deployable with clear bounded context separation  |
+
+> **Customization**: Project-specific structure decisions should be documented in `decisions/` as Architecture Decision Records (ADRs).
+
+---
+
+## Layered Architecture
+
+```
+Thin Routes / Controllers → Service Layer → Models / Data Access
+                              ↕
+                          Domain Logic
+```
+
+| Layer            | Responsibility                            | Rules                                              |
+| :--------------- | :---------------------------------------- | :------------------------------------------------- |
+| Routes           | HTTP handling, auth enforcement           | MAX 10 lines per handler, delegate to services      |
+| Services         | Business logic, validation, orchestration | Pure functions where possible, fully testable       |
+| Models / Data    | Database schema, relationships            | ORM-managed, migration-controlled                   |
+| Schemas          | Request/response contracts                | Validated models, explicit field constraints         |
+
+---
+
+## Database Conventions
+
+- **Migrations** for ALL schema changes — no manual SQL in production
+- Table names: `snake_case`, plural (`users`, `funnel_events`)
+- Column names: `snake_case`
+- Always include: `id` (UUID recommended), `created_at`, `updated_at`
+- Foreign keys: `<entity>_id` naming convention
+- Indexes: create for all foreign keys and frequent query columns
+- Soft deletes preferred over hard deletes for audit-sensitive data
+
+---
+
+## API Design Principles
+
+| Principle            | Standard                                                    |
+| :------------------- | :---------------------------------------------------------- |
+| Versioning           | URL-prefix (`/api/v1/`) or header-based — be consistent    |
+| Methods              | Standard HTTP methods and status codes (RESTful)            |
+| Response Format      | All endpoints return validated, structured JSON             |
+| Pagination           | Offset-based (`skip`/`limit`) or cursor-based — documented |
+| Error Format         | `{ "detail": "Human-readable message" }` minimum           |
+| Rate Limiting        | Documented per endpoint, enforced server-side               |
+
+---
+
+## Architecture Decision Records
+
+When making significant architectural decisions, document them using ADRs in the `decisions/` directory:
+
+- Choosing between architectural approaches (monolith vs microservices)
+- Selecting a technology (database, framework, library)
+- Establishing a pattern (event sourcing vs CRUD)
+- Making a trade-off (consistency vs availability)
+
+ADR format: `decisions/adr-NNN-<decision-title>.md`
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/architecture/SKILL.md` — deep architectural patterns (DDD, Clean Architecture, 12-Factor, SOLID)
+- **Agent**: `.agent/agents/architect.md` — architecture review process and checklists
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                                |
+| :------ | :--------- | :----------------------------------------------------- |
+| 1.0.0   | 2026-03-16 | Initial generic architecture enforcement rules for kit |
+

package/.agent/rules/quality-gate.md

@@ -0,0 +1,117 @@
+# Quality Gate Rules
+
+> **Priority**: HIGH — Enforced before implementation of new features and refactors
+> **Scope**: All workspaces — applies to `feat()` and `refactor()` tasks only
+
+---
+
+## Scope Filter
+
+| Task Type                         | Quality Gate Required? |
+| :-------------------------------- | :--------------------- |
+| `feat()` — new features           | ✅ Required            |
+| `refactor()` — structural changes | ✅ Required            |
+| `fix()` — bug fixes               | ❌ Skip                |
+| `chore()` — maintenance           | ❌ Skip                |
+| `docs()` — documentation          | ❌ Skip                |
+| `test()` — test additions         | ❌ Skip                |
+
+---
+
+## Pre-Execution Research Checklist
+
+Before implementing any in-scope task, **ALL** items must be completed. If any item is incomplete, execution is forbidden.
+
+### ☐ 1. Market Research Completed
+
+- Analyze **minimum 5** competitors or market leaders in the feature domain
+- Document how each implements the same or similar feature
+- Identify user adoption drivers: UX simplicity, accuracy, speed, transparency
+
+### ☐ 2. Outdated Pattern Verification
+
+- Verify the proposed approach does not use deprecated, abandoned, or criticized patterns
+- If outdated → propose a modern, evidence-based alternative (mandatory)
+- Document which patterns are considered harmful or legacy
+
+### ☐ 3. Baseline Parity Validation
+
+- Confirm the project **meets or exceeds** the current market baseline
+- Gaps must be explicitly listed with severity assessment
+- No gap left unaddressed without documented justification
+
+### ☐ 4. Enhancement Definition
+
+- Define exactly how the project **improves upon** the market baseline
+- Improvement must be intentional and documented
+- Consider: transparency, ethical automation, user-centricity, measurable outcomes
+
+### ☐ 5. Ethics & Automation Risk Assessment
+
+- Evaluate: privacy implications, AI bias risks, automation safety, user autonomy
+- Mitigation strategies must be documented for each identified risk
+- Data protection compliance must be considered for data-touching features
+
+### ☐ 6. Implementation Plan Prepared
+
+- Structured plan ready before execution begins
+- Plan includes research summary, key insights, risks, execution steps
+- Plan reviewed and approved before implementation may begin
+
+---
+
+## Enhancement Principle
+
+| Scenario                                    | Required Action                  |
+| :------------------------------------------ | :------------------------------- |
+| Competitors offer a standard                | **Meet or exceed** it            |
+| Competitors use unethical automation        | **Reject and improve**           |
+| Feature can be more transparent             | **Enhance by default**           |
+| Feature can be more user-centric            | **Enhance by default**           |
+| Feature can offer measurable outcomes       | **Enhance by default**           |
+
+**Never replicate patterns without improvement.**
+
+---
+
+## Cross-Cutting Deference
+
+Quality gate enforcement defers to specialized rules for domain-specific checks:
+
+- **Security**: See `rules/security.md` for input validation, auth, data protection
+- **Testing**: See `rules/testing.md` for coverage requirements, test types
+- **Code Quality**: See `rules/coding-style.md` for naming, file limits, immutability
+- **Documentation**: See `rules/documentation.md` for doc hierarchy, SSOT
+
+---
+
+## Reject & Escalate Rules
+
+| Condition                                   | Action                                 |
+| :------------------------------------------ | :------------------------------------- |
+| No market research provided                 | ❌ Reject — enforce research protocol  |
+| Clearly outdated or harmful patterns        | ❌ Reject — propose modern alternative |
+| Below-market standard solutions             | ❌ Reject — document gap               |
+| Ethics, privacy, or automation safety risks | ❌ Reject — document mitigation        |
+| Bypassing research ("just implement it")    | ❌ Reject — enforce protocol           |
+
+### Escalation Response
+
+> "This task cannot proceed in its current form, as it does not meet quality and market standards. Below are the identified risks and gaps. A revised, modern alternative is proposed."
+
+---
+
+## Related Resources
+
+- **Workflow**: `.agent/workflows/quality-gate.md` — step-by-step research procedure
+- **Skill**: `.agent/skills/brainstorming/SKILL.md` — Socratic questioning patterns
+- **Next Step**: After approval, proceed to `/plan` for implementation planning
+
+---
+
+## Version History
+
+| Version | Date       | Changes                                           |
+| :------ | :--------- | :------------------------------------------------ |
+| 1.0.0   | 2026-03-16 | Initial generic quality gate protocol for kit     |
+

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 |