agent-skill-kit 3.9.135

package/.agent/skills/system-design/rules/pattern-selection.md

@@ -0,0 +1,130 @@
+---
+name: pattern-selection
+description: Architecture pattern selection — decision trees for data access, domain logic, distribution, communication, with validation questions
+---
+
+# Pattern Selection Guidelines
+
+> Decision trees for choosing architectural patterns. Always ask: Is there a simpler solution?
+
+---
+
+## The 3 Questions (Before ANY Pattern)
+
+1. **Problem Solved**: What SPECIFIC problem does this pattern solve?
+2. **Simpler Alternative**: Is there a simpler solution?
+3. **Deferred Complexity**: Can we add this LATER when needed?
+
+> If you can't answer #1 clearly → don't use the pattern.
+
+---
+
+## Main Decision Tree
+
+```
+START: What's your MAIN concern?
+
+┌─ Data Access Complexity?
+│  ├─ HIGH (complex queries, testing needed)
+│  │  → Repository Pattern + Unit of Work
+│  │  VALIDATE: Will data source change frequently?
+│  │     ├─ YES → Repository worth the indirection
+│  │     └─ NO  → Consider simpler ORM direct access
+│  └─ LOW (simple CRUD, single database)
+│     → ORM directly (Prisma, Drizzle)
+│     Simpler = Better, Faster
+│
+├─ Business Rules Complexity?
+│  ├─ HIGH (domain logic, rules vary by context)
+│  │  → Domain-Driven Design
+│  │  VALIDATE: Do you have domain experts on team?
+│  │     ├─ YES → Full DDD (Aggregates, Value Objects)
+│  │     └─ NO  → Partial DDD (rich entities, clear boundaries)
+│  └─ LOW (mostly CRUD, simple validation)
+│     → Transaction Script pattern
+│     Simpler = Better, Faster
+│
+├─ Independent Scaling Needed?
+│  ├─ YES (different components scale differently)
+│  │  → Microservices WORTH the complexity
+│  │  REQUIREMENTS (ALL must be true):
+│  │    - Clear domain boundaries
+│  │    - Team > 10 developers
+│  │    - Different scaling needs per service
+│  │  IF NOT ALL MET → Modular Monolith instead
+│  └─ NO (everything scales together)
+│     → Modular Monolith
+│     Can extract services later when proven needed
+│
+└─ Real-time Requirements?
+   ├─ HIGH (immediate updates, multi-user sync)
+   │  → Event-Driven Architecture
+   │  → Message Queue (RabbitMQ, Redis, Kafka)
+   │  VALIDATE: Can you handle eventual consistency?
+   │     ├─ YES → Event-driven valid
+   │     └─ NO  → Synchronous with polling
+   └─ LOW (eventual consistency acceptable)
+      → Synchronous (REST/GraphQL)
+      Simpler = Better, Faster
+```
+
+---
+
+## Communication Pattern Selection
+
+```
+How do services communicate?
+
+┌─ Synchronous (request-response)?
+│  ├─ Public API → REST (standard, cacheable)
+│  ├─ Internal services → gRPC (fast, typed)
+│  ├─ Flexible queries → GraphQL (client-driven)
+│  └─ Real-time bidirectional → WebSocket
+│
+└─ Asynchronous (fire-and-forget)?
+   ├─ Simple job queue → BullMQ (Redis-based)
+   ├─ Point-to-point → RabbitMQ (routing, reliability)
+   ├─ High throughput stream → Kafka (log, replay)
+   └─ Cloud-native → AWS SQS/SNS, GCP Pub/Sub
+```
+
+### Message Broker Selection
+
+| Factor | BullMQ | RabbitMQ | Kafka |
+|--------|--------|----------|-------|
+| **Best for** | Background jobs | Task routing | Event streaming |
+| **Throughput** | Medium | Medium | Very High |
+| **Ordering** | Per queue | Per queue | Per partition |
+| **Replay** | ❌ | ❌ | ✅ |
+| **Complexity** | Low | Medium | High |
+| **Persistence** | Redis | Disk | Disk (replicated) |
+| **Use when** | <10K msgs/sec | Routing logic | >10K msgs/sec, audit |
+
+---
+
+## Red Flags (Anti-patterns)
+
+| Pattern | Anti-pattern Signal | Simpler Alternative |
+|---------|-------------------|---------------------|
+| Microservices | "We might need to scale someday" | Start monolith, extract later |
+| Clean/Hexagonal | Dozens of interfaces for simple CRUD | Concrete first, interfaces later |
+| Event Sourcing | "Audit trail would be nice" | Append-only audit log table |
+| CQRS | Read/write look the same | Single model, add CQRS when diverged |
+| Repository | Single database, simple queries | ORM direct access |
+| DDD | No domain experts, simple CRUD | Transaction Script |
+| GraphQL | Single client, simple queries | REST |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [context-discovery.md](context-discovery.md) | Classify project first |
+| [patterns-reference.md](patterns-reference.md) | Quick pattern lookup |
+| [trade-off-analysis.md](trade-off-analysis.md) | Document your choice |
+| [examples.md](examples.md) | See real implementations |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/system-design/rules/patterns-reference.md

@@ -0,0 +1,110 @@
+---
+name: patterns-reference
+description: Architecture patterns quick reference — data access, domain, distributed, communication, resilience, and observability patterns
+---
+
+# Architecture Patterns Reference
+
+> Quick lookup for common patterns. Check When to Use vs When NOT to Use before adopting.
+
+---
+
+## Data Access Patterns
+
+| Pattern | What It Does | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-------------|-----------------|:----------:|
+| **Active Record** | Object = row, methods = queries | Simple CRUD, rapid prototyping | Complex queries, multiple sources | Low |
+| **Repository** | Abstract data access behind interface | Testing, multiple sources, complex queries | Simple CRUD, single DB | Medium |
+| **Unit of Work** | Track changes, commit as single transaction | Complex multi-entity writes | Simple single-table operations | High |
+| **Data Mapper** | Separate domain from persistence | Rich domain model, performance tuning | Simple CRUD, rapid dev | High |
+
+**Decision:** Start with Active Record / ORM direct. Add Repository when testing demands or source changes.
+
+---
+
+## Domain Logic Patterns
+
+| Pattern | What It Does | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-------------|-----------------|:----------:|
+| **Transaction Script** | Procedural — one function per operation | Simple CRUD, thin business logic | Complex rules, many edge cases | Low |
+| **Table Module** | One class per table with record logic | Record-based validation | Rich behavior across entities | Low |
+| **Domain Model** | Objects with behavior (OOP) | Complex business logic, state machines | Simple CRUD, no invariants | Medium |
+| **DDD (Full)** | Aggregates, Value Objects, bounded contexts | Complex domain, domain experts available | Simple domain, no experts | High |
+
+**Decision:** Transaction Script is default. Upgrade to Domain Model when rules exceed simple validation.
+
+---
+
+## Distributed System Patterns
+
+| Pattern | What It Does | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-------------|-----------------|:----------:|
+| **Modular Monolith** | Single deployment, internal module boundaries | Small-medium teams, unclear boundaries | Clear contexts, different scales | Medium |
+| **Microservices** | Independent services, independent deploy | Different scales, large teams (10+) | Small teams, simple domain | Very High |
+| **Event-Driven** | Publish events, subscribers react | Loose coupling, real-time, audit trail | Simple workflows, strong consistency required | High |
+| **CQRS** | Separate read/write models | Read/write performance diverges | Same data shape for read/write | High |
+| **Saga** | Distributed transactions via compensation | Cross-service transactions | Single database, simple ACID | High |
+| **Event Sourcing** | Store events, derive state | Full audit trail, temporal queries | Simple state, no replay needs | Very High |
+
+**Decision:** Modular Monolith is default. Extract microservices only when 3 criteria met (clear boundaries + team >10 + different scaling).
+
+---
+
+## Communication Patterns
+
+| Pattern | What It Does | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-------------|-----------------|:----------:|
+| **REST** | Resource-based HTTP API | Standard CRUD, public APIs, caching | Real-time, complex queries | Low |
+| **GraphQL** | Client-driven queries, single endpoint | Multi-client, flexible queries | Simple CRUD, heavy caching | Medium |
+| **gRPC** | Binary protocol, code-gen, streaming | Internal services, high perf | Public APIs, browser clients | Medium |
+| **WebSocket** | Persistent bidirectional connection | Real-time updates, chat, collaboration | Simple request-response | Medium |
+| **SSE** | Server-push, one-directional | Live feeds, notifications | Bidirectional communication | Low |
+
+---
+
+## Resilience Patterns
+
+| Pattern | What It Does | When to Use |
+|---------|-------------|-------------|
+| **Circuit Breaker** | Stop calling failing service, fallback | External service calls |
+| **Retry with Backoff** | Retry transient failures with delay | Network errors, 503s |
+| **Bulkhead** | Isolate failure to prevent cascade | Multiple service dependencies |
+| **Timeout** | Limit wait time for external calls | Every external call |
+| **Rate Limiter** | Limit request throughput | API endpoints, external APIs |
+
+---
+
+## Observability Patterns
+
+| Pattern | What It Does | Tool Examples |
+|---------|-------------|---------------|
+| **Structured Logging** | JSON logs with context | Pino, Winston → Loki |
+| **Distributed Tracing** | Track requests across services | OpenTelemetry → Jaeger/Tempo |
+| **Metrics** | Numeric measurements over time | Prometheus → Grafana |
+| **Health Checks** | Endpoint reporting service health | `/health`, `/ready` |
+| **Alerting** | Notify on threshold breach | PagerDuty, Grafana Alerting |
+
+---
+
+## Simplicity Principle
+
+**"Start simple, add complexity only when proven necessary."**
+
+- You can always add patterns later
+- Removing complexity is MUCH harder than adding it
+- When in doubt, choose the simpler option
+- If you can't explain why you need a pattern in one sentence → you don't need it
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [pattern-selection.md](pattern-selection.md) | Decision trees |
+| [examples.md](examples.md) | Real implementations |
+| [trade-off-analysis.md](trade-off-analysis.md) | Document choices |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/system-design/rules/trade-off-analysis.md

@@ -0,0 +1,169 @@
+---
+name: trade-off-analysis
+description: Trade-off analysis framework — ADR template, common trade-off dimensions, filled example, and decision storage
+---
+
+# Trade-off Analysis & ADR
+
+> Document every architectural decision with trade-offs. Future-you will thank present-you.
+
+---
+
+## Common Trade-off Dimensions
+
+| Dimension | Trade-off |
+|-----------|-----------|
+| **Simplicity ↔ Flexibility** | Simple code is rigid; flexible code is complex |
+| **Speed ↔ Quality** | Ship fast = tech debt; polish = slower delivery |
+| **Consistency ↔ Availability** | Strong consistency = lower availability (CAP) |
+| **Coupling ↔ Complexity** | Tight coupling = simple; loose coupling = more infra |
+| **Build ↔ Buy** | Build = control + maintenance; Buy = cost + vendor lock |
+| **Monolith ↔ Microservices** | Monolith = simple ops; Micro = independent scale + deploy complexity |
+| **SQL ↔ NoSQL** | SQL = consistency + joins; NoSQL = scale + flexibility |
+
+---
+
+## Decision Framework
+
+For EACH architectural component, document:
+
+```markdown
+## Architecture Decision Record
+
+### Context
+- **Problem**: [What problem are we solving?]
+- **Constraints**: [Team size, scale, timeline, budget]
+
+### Options Considered
+
+| Option | Pros | Cons | Complexity | When Valid |
+|--------|------|------|------------|-----------|
+| Option A | Benefit 1 | Cost 1 | Low | [Conditions] |
+| Option B | Benefit 2 | Cost 2 | High | [Conditions] |
+
+### Decision
+**Chosen**: [Option X]
+
+### Rationale
+1. [Reason 1 — tied to constraints]
+2. [Reason 2 — tied to requirements]
+
+### Trade-offs Accepted
+- [What we're giving up]
+- [Why this is acceptable]
+
+### Consequences
+- **Positive**: [Benefits we gain]
+- **Negative**: [Costs/risks we accept]
+- **Mitigation**: [How we'll address negatives]
+
+### Revisit Trigger
+- [When to reconsider this decision]
+```
+
+---
+
+## Filled Example: Database Selection
+
+```markdown
+# ADR-002: PostgreSQL over MongoDB
+
+## Status
+Accepted
+
+## Context
+E-commerce SaaS with orders, inventory, and user management.
+Team of 5, all familiar with SQL. Need ACID for financial transactions.
+
+## Options Considered
+
+| Option | Pros | Cons | Complexity |
+|--------|------|------|-----------|
+| PostgreSQL | ACID, joins, mature, JSON support | Harder horizontal scale | Low |
+| MongoDB | Flexible schema, horizontal scale | No joins, eventual consistency | Medium |
+| CockroachDB | Distributed SQL, ACID | Newer, smaller ecosystem | High |
+
+## Decision
+**Chosen**: PostgreSQL
+
+## Rationale
+1. Financial transactions require ACID (orders + payments)
+2. Team already proficient in SQL — no learning curve
+3. JSON column covers semi-structured data needs
+4. Supabase/Neon provide managed PG with good DX
+
+## Trade-offs Accepted
+- Horizontal scaling harder → acceptable at <100K users
+- Single point of failure → mitigated by managed hosting + replicas
+
+## Consequences
+- **Positive**: Strong consistency for orders, familiar tooling, Prisma/Drizzle support
+- **Negative**: Must shard manually if >100K concurrent writes
+- **Mitigation**: Read replicas for read scaling, revisit if write-heavy
+
+## Revisit Trigger
+- Write throughput >10K/sec consistently
+- Need geo-distributed database
+- Schema flexibility becomes painful
+```
+
+---
+
+## ADR Compact Template
+
+```markdown
+# ADR-[XXX]: [Decision Title]
+
+## Status
+Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]
+
+## Context
+[What problem? What constraints?]
+
+## Decision
+[What we chose — be specific]
+
+## Rationale
+[Why — tie to requirements and constraints]
+
+## Trade-offs
+[What we're giving up — be honest]
+
+## Consequences
+- **Positive**: [Benefits]
+- **Negative**: [Costs]
+- **Mitigation**: [How to address]
+```
+
+---
+
+## ADR Storage
+
+```
+docs/
+└── architecture/
+    ├── adr-001-use-nextjs.md
+    ├── adr-002-postgresql-over-mongodb.md
+    ├── adr-003-modular-monolith.md
+    └── adr-004-jwt-over-session.md
+```
+
+**Rules:**
+- Sequential numbering (never reuse numbers)
+- Deprecated ADRs stay (append "Superseded by ADR-XXX")
+- Review ADRs quarterly against revisit triggers
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [context-discovery.md](context-discovery.md) | Gather context first |
+| [pattern-selection.md](pattern-selection.md) | Choose patterns |
+| [patterns-reference.md](patterns-reference.md) | Pattern comparison |
+| [examples.md](examples.md) | See full architecture examples |
+
+---
+
+⚡ PikaKit v3.9.134