izanagi-ai 2.0.0

package/architecture/clean-architecture.md

@@ -0,0 +1,98 @@
+# Architecture: Clean Architecture
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, DDD Specialist
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Clean Architecture enforces dependency inversion: domain at the center, application use cases around it, infrastructure and delivery at the outer rings. Nothing in the inner ring depends on anything in the outer rings.
+
+---
+
+## Layer Structure
+
+```
+┌──────────────────────────────────────────┐
+│  Delivery (Controllers, API, CLI)       │  → depends on Application
+│  ┌────────────────────────────────────┐  │
+│  │  Infrastructure (DB, Queue, Mail)  │  │  → depends on Application
+│  │  ┌──────────────────────────────┐  │  │
+│  │  │  Application (Use Cases)     │  │  │  → depends on Domain only
+│  │  │  ┌────────────────────────┐  │  │  │
+│  │  │  │  Domain (Entities,     │  │  │  │
+│  │  │  │  ValueObjects,        │  │  │  │  → zero dependencies
+│  │  │  │  Domain Services)     │  │  │  │
+│  │  │  └────────────────────────┘  │  │  │
+│  │  └──────────────────────────────┘  │  │
+│  └────────────────────────────────────┘  │
+└──────────────────────────────────────────┘
+```
+
+---
+
+## Directory Structure
+
+```
+src/
+├── Domain/
+│   ├── Entities/
+│   ├── ValueObjects/
+│   ├── Events/
+│   ├── Repositories/   (interfaces)
+│   └── Services/       (domain services)
+│
+├── Application/
+│   ├── UseCases/
+│   ├── DTOs/
+│   ├── Ports/          (input/output interfaces)
+│   └── Exceptions/
+│
+├── Infrastructure/
+│   ├── Persistence/    (repository implementations)
+│   ├── Queue/
+│   ├── Mail/
+│   └── Cache/
+│
+└── Delivery/
+    ├── Controllers/
+    ├── Requests/
+    └── Responses/
+```
+
+---
+
+## Dependency Rule
+
+```php
+// Domain — zero dependencies
+class Order { ... }
+
+// Application — depends on Domain only
+class PlaceOrderUseCase
+{
+    public function __construct(
+        private OrderRepository $repository,  // Interface from Domain
+        private EventDispatcher $dispatcher,  // Interface from Application Ports
+    ) {}
+}
+
+// Infrastructure — implements Domain interfaces
+class PostgresOrderRepository implements OrderRepository { ... }
+
+// Delivery — uses Application
+class OrderController
+{
+    public function __construct(
+        private PlaceOrderUseCase $useCase
+    ) {}
+}
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Layers, directory structure, dependency rule.

package/architecture/cqrs-specialist.md

@@ -0,0 +1,102 @@
+# Architecture: CQRS Specialist
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, Event-Driven Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+CQRS Specialist separates read and write models. Commands change state, queries read state. Read models can be optimized for queries (denormalized, different DB), write models enforce domain invariants.
+
+---
+
+## When to Use CQRS
+
+```yaml
+use:
+  - Complex domain with different read/write shapes
+  - High read volume (reads scale independently)
+  - Event sourcing (events write, projections read)
+  - Reporting needs (read models optimized for queries)
+
+avoid:
+  - Simple CRUD (overhead without benefit)
+  - Single database (no need for separate models yet)
+  - Small team (complexity tax)
+```
+
+---
+
+## Structure
+
+```
+Commands:
+  POST /orders/place
+  Body: { cartId, customerId }
+  → Command: PlaceOrderCommand
+  → Handler: PlaceOrderHandler
+  → Event: OrderPlaced
+
+Queries:
+  GET /orders/active
+  → Query: GetActiveOrdersQuery
+  → Handler: GetActiveOrdersHandler
+  → Returns: ReadModel (denormalized)
+```
+
+---
+
+## Implementation
+
+```php
+// Command
+class PlaceOrderCommand
+{
+    public function __construct(
+        public readonly string $cartId,
+        public readonly string $customerId,
+    ) {}
+}
+
+// Command Handler (write model)
+class PlaceOrderHandler
+{
+    public function __construct(
+        private OrderRepository $repository,
+        private EventDispatcher $dispatcher,
+    ) {}
+
+    public function handle(PlaceOrderCommand $command): void
+    {
+        $order = Order::place(
+            CartId::fromString($command->cartId),
+            CustomerId::fromString($command->customerId),
+        );
+        $this->repository->save($order);
+        $this->dispatcher->dispatch(new OrderPlaced($order->getId()));
+    }
+}
+
+// Query Handler (read model — optimized for queries)
+class GetActiveOrdersHandler
+{
+    public function __construct(
+        private OrderReadModel $readModel,  // Separate from write repo
+    ) {}
+
+    public function handle(GetActiveOrdersQuery $query): array
+    {
+        return $this->readModel->getActiveOrders(
+            $query->customerId,
+        );
+    }
+}
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. When to use, structure, implementation.

package/architecture/ddd-specialist.md

@@ -0,0 +1,97 @@
+# Architecture: DDD Specialist
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+DDD Specialist applies Domain-Driven Design: ubiquitous language, bounded contexts, aggregates, entities, value objects, domain events, and repositories. Ensures the codebase speaks the language of the business.
+
+---
+
+## DDD Building Blocks
+
+```yaml
+entity: has identity (id), mutable, tracked through lifecycle
+  - User, Order, Product
+
+value_object: immutable, defined by attributes, no identity
+  - Address, Money, Email
+
+aggregate: cluster of entities/VOs treated as a unit
+  - Order (with OrderItems), consistency boundary
+
+repository: collection-like interface for aggregates
+  - OrderRepository, UserRepository
+
+domain_event: something that happened (past tense)
+  - OrderPlaced, PaymentReceived
+
+domain_service: stateless operation that doesn't fit an entity
+  - DiscountCalculator, ShippingCostService
+```
+
+---
+
+## Ubiquitous Language
+
+```yaml
+business_term: "Order"
+code: App\Domain\Order\Order.php
+
+business_term: "Place Order"
+code: App\Domain\Order\Commands\PlaceOrder.php
+
+business_term: "Order Placed"
+code: App\Domain\Order\Events\OrderPlaced.php
+
+business_term: "Order Total"
+code: App\Domain\Order\ValueObjects\OrderTotal.php
+```
+
+---
+
+## Aggregate Example
+
+```php
+class Order extends AggregateRoot
+{
+    private function __construct(
+        private readonly OrderId $id,
+        private readonly Cart $cart,
+        private OrderStatus $status,
+        private \DateTimeImmutable $placedAt,
+    ) {}
+
+    public static function place(Cart $cart, CustomerId $customerId): self
+    {
+        if ($cart->isEmpty()) {
+            throw new CannotPlaceEmptyOrder($cart->getId());
+        }
+
+        $order = new self(
+            OrderId::generate(),
+            $cart,
+            OrderStatus::Pending,
+            new \DateTimeImmutable()
+        );
+
+        $order->recordEvent(new OrderPlaced(
+            orderId: $order->id,
+            customerId: $customerId,
+            total: $cart->total(),
+        ));
+
+        return $order;
+    }
+}
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Building blocks, language, aggregate example.

package/architecture/event-driven-architect.md

@@ -0,0 +1,79 @@
+# Architecture: Event-Driven Architect
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, Microservices Expert
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Event-Driven Architect designs systems where services communicate through events. Defines event schemas, idempotency, at-least-once delivery, dead letter queues, and event sourcing when appropriate.
+
+---
+
+## Core Concepts
+
+```yaml
+event: a fact that happened in the past (past tense)
+  - "user.registered", "order.placed", "payment.received"
+
+message_broker:
+  - RabbitMQ: reliable, routing flexibility
+  - Kafka: high throughput, event sourcing, replay
+  - Redis Pub/Sub: lightweight, no persistence
+
+patterns:
+  event_notification: fire and forget
+  event_carried_state: include enough data for consumers
+  saga: distributed transaction via events + compensating actions
+  event_sourcing: store events as source of truth
+  CQRS: separate read model updated by events
+```
+
+---
+
+## Event Schema
+
+```json
+{
+  "id": "evt_abc123",
+  "type": "user.registered",
+  "version": 1,
+  "timestamp": "2026-07-17T12:00:00Z",
+  "producer": "user-service",
+  "data": {
+    "user_id": "usr_456",
+    "email": "user@test.com"
+  },
+  "metadata": {
+    "correlation_id": "req_789",
+    "cause": "user.registration.submitted"
+  }
+}
+```
+
+---
+
+## Idempotency
+
+Every event consumer must handle duplicate events:
+
+```php
+// Consumer
+public function handle(UserRegistered $event): void
+{
+    if ($this->alreadyProcessed($event->id)) {
+        return; // Idempotent — already handled
+    }
+
+    $this->sendWelcomeEmail($event->email);
+    $this->markProcessed($event->id);
+}
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Events, brokers, patterns, idempotency.

package/architecture/hexagonal-architecture.md

@@ -0,0 +1,96 @@
+# Architecture: Hexagonal Architecture (Ports & Adapters)
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Hexagonal Architecture (Ports & Adapters) isolates the core application from external concerns through ports (interfaces) and adapters (implementations). The core has no dependency on frameworks, databases, or delivery mechanisms.
+
+---
+
+## Structure
+
+```
+       ┌─────────────┐
+       │   Adapter   │  (Inbound: Controller, CLI, Queue Consumer)
+       │  (Delivery) │
+       └──────┬──────┘
+              │ Port (inbound interface)
+       ┌──────▼──────┐
+       │   CORE      │  (Application + Domain)
+       │  (no deps)  │
+       └──────┬──────┘
+              │ Port (outbound interface)
+       ┌──────▼──────┐
+       │   Adapter   │  (Outbound: PostgreSQL, Redis, Mail, HTTP)
+       │ (Infra)     │
+       └─────────────┘
+```
+
+---
+
+## Ports & Adapters
+
+```php
+// Port (outbound interface)
+interface OrderRepository
+{
+    public function save(Order $order): void;
+    public function findById(OrderId $id): ?Order;
+}
+
+// Adapter (outbound implementation)
+class PostgresOrderRepository implements OrderRepository
+{
+    public function __construct(private Connection $db) {}
+    
+    public function save(Order $order): void
+    {
+        $this->db->insert('orders', [
+            'id' => $order->getId()->toString(),
+            'total' => $order->getTotal()->toCents(),
+            'status' => $order->getStatus()->value,
+        ]);
+    }
+    
+    public function findById(OrderId $id): ?Order
+    {
+        $row = $this->db->fetch('SELECT * FROM orders WHERE id = ?', [$id->toString()]);
+        return $row ? $this->hydrate($row) : null;
+    }
+}
+```
+
+---
+
+## Key Benefit
+
+Swap infrastructure without touching core:
+
+```php
+// Test adapter (instead of PostgresOrderRepository)
+class InMemoryOrderRepository implements OrderRepository
+{
+    private array $orders = [];
+
+    public function save(Order $order): void
+    {
+        $this->orders[$order->getId()->toString()] = $order;
+    }
+
+    public function findById(OrderId $id): ?Order
+    {
+        return $this->orders[$id->toString()] ?? null;
+    }
+}
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Ports & Adapters, example, testability.

package/architecture/microservices-expert.md

@@ -0,0 +1,83 @@
+# Architecture: Microservices Expert
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, DevOps Engineer, API Designer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Microservices Expert designs systems of independently deployable services communicating via APIs or events. Identifies bounded contexts (DDD), defines service contracts, and handles interservice communication, data consistency, and observability.
+
+---
+
+## When to Use
+
+```yaml
+use_microservices:
+  - Multiple teams working independently
+  - Different scaling requirements per domain
+  - Polyglot persistence (different DBs per service)
+  - Independent deployment cycles needed
+
+prefer_monolith:
+  - Single team < 5 developers
+  - Simple CRUD application
+  - Early-stage product (MVP)
+  - No clear bounded context boundaries yet
+```
+
+---
+
+## Key Patterns
+
+```yaml
+communication:
+  sync: REST/gRPC for queries, command responses
+  async: Events (RabbitMQ/Kafka) for commands, notifications
+
+data:
+  database_per_service: each service owns its data
+  saga: distributed transaction (choreography or orchestration)
+  CQRS: separate read/write models per service
+
+deployment:
+  containerized: Docker + Kubernetes
+  per_service_pipeline: each service has its own CI/CD
+  blue_green: zero-downtime deployments
+
+observability:
+  logging: structured JSON, correlation ID per request
+  metrics: RED metrics (Rate, Errors, Duration) per service
+  tracing: distributed tracing (OpenTelemetry + Jaeger)
+```
+
+---
+
+## Service Template
+
+```yaml
+service:
+  name: "user-service"
+  language: "PHP / Laravel"
+  database: "postgresql:16"
+  communication: "REST (internal) + Events (RabbitMQ)"
+  
+  endpoints:
+    - "POST /api/v1/users"
+    - "GET /api/v1/users/{id}"
+  
+  events_publishes:
+    - "user.created"
+    - "user.updated"
+  
+  events_subscribes:
+    - "order.completed → update user stats"
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Patterns, when to use/avoid, template.

package/architecture/monolith-expert.md

@@ -0,0 +1,67 @@
+# Architecture: Monolith Expert
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Monolith Expert defends the monolith as a valid, often superior architecture for most projects. Designs modular monoliths with clear bounded contexts, strict module boundaries, and a migration path toward microservices only when justified.
+
+---
+
+## Advantages
+
+- Simple deployment (1 artifact).
+- No network latency between modules.
+- Atomic transactions across domains.
+- Easy debugging and testing.
+- Lower operational complexity.
+- Faster development velocity (early stage).
+
+---
+
+## Modular Monolith Structure
+
+```
+app/
+├── Modules/
+│   ├── User/
+│   │   ├── Controllers/
+│   │   ├── Services/
+│   │   ├── Repositories/
+│   │   ├── Events/
+│   │   └── Models/
+│   ├── Payment/
+│   │   └── ...
+│   └── Order/
+│       └── ...
+├── Shared/
+│   ├── Kernel.php
+│   └── Helpers/
+```
+
+---
+
+## Migration Path
+
+```
+Monolith → Modular Monolith → (if needed) → Microservices
+
+Rules:
+1. Never start with microservices
+2. Extract bounded contexts into modules first
+3. Define strict interfaces between modules
+4. Only extract to separate service when:
+   - Module needs independent scaling
+   - Module needs a different tech stack
+   - Team needs independent deploys
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Modular monolith, migration path.

package/architecture/repository-pattern.md

@@ -0,0 +1,73 @@
+# Architecture: Repository Pattern
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, DDD Specialist
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Repository Pattern mediates between domain and data mapping layers, acting like an in-memory collection of aggregate roots. It provides a clean separation between business logic and data access.
+
+---
+
+## Contract
+
+```php
+interface UserRepository
+{
+    public function findById(UserId $id): ?User;
+    public function findByEmail(string $email): ?User;
+    public function save(User $user): void;
+    public function delete(UserId $id): void;
+}
+```
+
+## Implementation
+
+```php
+class PostgresUserRepository implements UserRepository
+{
+    public function __construct(private Connection $db) {}
+
+    public function findById(UserId $id): ?User
+    {
+        $row = $this->db->fetch('SELECT * FROM users WHERE id = ?', [$id->toString()]);
+        return $row ? $this->hydrate($row) : null;
+    }
+
+    public function save(User $user): void
+    {
+        $this->db->upsert('users', [
+            'id' => $user->getId()->toString(),
+            'name' => $user->getName(),
+            'email' => $user->getEmail(),
+        ]);
+    }
+
+    private function hydrate(array $row): User
+    {
+        return new User(
+            UserId::fromString($row['id']),
+            $row['name'],
+            $row['email'],
+        );
+    }
+}
+```
+
+---
+
+## Rules
+
+- Repository per aggregate root (not per table).
+- One `save()` method handles both insert and update.
+- Repositories return domain objects, not arrays.
+- Repositories hide the data source (SQL, API, file).
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Contract, implementation, rules.