agent-skill-kit 3.9.135

package/.agent/skills/system-design/rules/engineering-spec.md

@@ -0,0 +1,437 @@
+---
+name: system-design-engineering-spec
+description: Full 21-section engineering spec — context discovery, ADR format, pattern selection, 6-item validation checklist
+title: "System Design - Engineering Specification"
+impact: MEDIUM
+impactDescription: "Moderate improvement to quality or maintainability"
+tags: engineering, spec
+---
+
+# System Design — Engineering Specification
+
+> Production-grade specification for architectural decision-making at FAANG scale.
+
+---
+
+## 1. Overview
+
+System Design provides a structured framework for architectural decision-making: requirements analysis (via context-discovery), trade-off evaluation (via ADR format), pattern selection (via decision trees), and architecture validation (6-item checklist). The skill operates as an **Expert (decision tree)** — it produces architecture recommendations, trade-off analyses, ADR documents, and pattern selections. It does not implement systems, write code, or deploy infrastructure.
+
+**Contract Version:** 2.0.0
+**Backward Compatibility:** breaking (first hardened version)
+**Breaking Changes:** None — new spec for first hardening
+
+---
+
+## 2. Problem Statement
+
+Architecture decisions at scale face four quantified problems:
+
+| Problem | Measurement | Impact |
+|---------|-------------|--------|
+| No requirements discovery | 50% of projects skip context questions | Wrong architecture |
+| Undocumented decisions | 60% of architecture choices lack ADRs | Lost rationale |
+| Premature complexity | 45% of projects over-engineer from day one | Wasted effort |
+| Wrong pattern selection | 35% of projects use mismatched patterns | Refactoring debt |
+
+System Design eliminates these with structured context discovery (project classification), ADR templates (formal trade-off documentation), pattern decision trees (deterministic routing), and a validation checklist (6 mandatory checks).
+
+---
+
+## 3. Design Goals
+
+| ID | Goal | Measurable Constraint |
+|----|------|-----------------------|
+| G1 | Requirements analysis | Structured context discovery with project classification |
+| G2 | Trade-off evaluation | ADR format with explicit pros/cons/consequences |
+| G3 | Pattern selection | Decision trees routing to specific patterns |
+| G4 | Architecture validation | 6-item checklist before finalization |
+| G5 | Simplicity principle | Start simple; add complexity only when proven necessary |
+| G6 | Reference implementations | 3 example types: MVP, SaaS, Enterprise |
+
+---
+
+## 4. Non-Goals
+
+| ID | Excluded | Rationale |
+|----|----------|-----------|
+| NG1 | API design specifics | Owned by `api-architect` skill |
+| NG2 | Database schema design | Owned by `data-modeler` skill |
+| NG3 | Deployment configuration | Owned by `cicd-pipeline` skill |
+| NG4 | Code implementation | Architecture guidance only |
+| NG5 | Performance benchmarking | Owned by `perf-optimizer` skill |
+| NG6 | Security audit | Owned by `security-scanner` skill |
+
+---
+
+## 5. System Boundaries
+
+| Boundary | Owned | Not Owned |
+|----------|-------|-----------|
+| Context discovery | Project classification questions | Requirements gathering |
+| Trade-off analysis | ADR template + framework | Decision enforcement |
+| Pattern selection | Decision trees for routing | Pattern implementation |
+| Architecture validation | 6-item checklist | Testing/verification |
+| Examples | MVP, SaaS, Enterprise references | Production deployments |
+
+**Side-effect boundary:** System Design produces architecture recommendations, ADR documents, and pattern selections. It does not write code, create infrastructure, or modify systems.
+
+---
+
+## 6. Integration Model
+
+### 6.1 Agent Contract
+
+#### Input Schema
+
+```
+Request_Type: string          # "context-discovery" | "trade-off" | "pattern-selection" |
+                              # "validation" | "example" | "full-review"
+Context: {
+  project_type: string | null # "mvp" | "saas" | "enterprise" | null
+  scale: string | null        # "startup" | "growth" | "enterprise"
+  constraints: Array<string> | null  # e.g., ["latency < 100ms", "global distribution"]
+  current_patterns: Array<string> | null  # Existing patterns in use
+  decision_topic: string | null  # What decision needs analysis
+}
+contract_version: string      # "2.0.0"
+```
+
+#### Output Schema
+
+```
+Status: "success" | "error"
+Data: {
+  context: {
+    classification: string
+    questions: Array<string>
+    constraints_identified: Array<string>
+  } | null
+  trade_off: {
+    title: string
+    status: string            # "proposed" | "accepted" | "deprecated"
+    context: string
+    options: Array<{
+      name: string
+      pros: Array<string>
+      cons: Array<string>
+    }>
+    decision: string
+    consequences: Array<string>
+  } | null
+  pattern: {
+    recommended: string
+    rationale: string
+    alternatives: Array<string>
+    anti_patterns: Array<string>
+  } | null
+  validation: {
+    checklist: Array<{
+      item: string
+      status: boolean
+      notes: string | null
+    }>
+    passed: boolean
+  } | null
+  example: {
+    type: string              # "mvp" | "saas" | "enterprise"
+    architecture: string
+    patterns_used: Array<string>
+  } | null
+  metadata: {
+    contract_version: string
+    backward_compatibility: string
+  }
+}
+Error: ErrorSchema | null
+```
+
+#### Error Schema
+
+```
+Code: string                  # From Error Taxonomy (Section 11)
+Message: string
+Request_Type: string
+Recoverable: boolean
+```
+
+#### Deterministic Guarantees
+
+- Context discovery produces the same questions for the same project type.
+- Pattern selection routes deterministically based on scale + constraints.
+- Validation checklist is fixed: 6 items, deterministic pass/fail.
+- ADR format is fixed: title, status, context, options, decision, consequences.
+- Same project type + same constraints = same pattern recommendation.
+
+#### What Agents May Assume
+
+- Context discovery includes project classification.
+- Trade-off analysis follows ADR format.
+- Pattern selection uses documented decision trees.
+- Validation checklist covers 6 mandatory items.
+
+#### What Agents Must NOT Assume
+
+- Recommended pattern is the only valid option.
+- All constraints are known upfront.
+- Architecture is final after first pass.
+- Simpler alternative has been considered unless explicitly stated.
+
+#### Side-Effect Boundaries
+
+| Operation | Side Effects |
+|-----------|-------------|
+| Context discovery | None; questions output |
+| Trade-off analysis | None; ADR document |
+| Pattern selection | None; recommendation |
+| Validation | None; checklist results |
+| Example | None; reference output |
+
+### 6.2 Workflow Contract
+
+#### Invocation Pattern
+
+```
+1. Invoke context-discovery to classify project and identify constraints
+2. Invoke pattern-selection for architecture pattern routing
+3. Invoke trade-off for ADR documentation of key decisions
+4. Invoke validation to verify 6-item checklist
+5. Implement architecture (caller's responsibility)
+```
+
+#### Execution Guarantees
+
+- Each invocation produces a complete output.
+- All operations are independent (can be invoked in any order).
+
+#### Failure Propagation Model
+
+| Failure Severity | Propagation | Workflow Action |
+|-----------------|-------------|-----------------|
+| Unknown project type | Return error | Specify mvp, saas, or enterprise |
+| Missing constraints | Return warning | Provide constraints for better routing |
+| Invalid request type | Return error | Use supported type |
+
+#### Retry Boundaries
+
+- Zero internal retries. Deterministic output.
+
+#### Isolation Model
+
+- Each invocation is stateless and independent.
+
+#### Idempotency Expectations
+
+| Operation | Idempotent | Notes |
+|-----------|-----------|-------|
+| Context discovery | Yes | Same type = same questions |
+| Trade-off | Yes | Same topic = same ADR structure |
+| Pattern selection | Yes | Same constraints = same pattern |
+| Validation | Yes | Same inputs = same checklist |
+
+---
+
+## 7. Execution Model
+
+### 2-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Classify** | Parse project type, scale, constraints | Classification |
+| **Guide** | Generate context questions, pattern recommendation, ADR, or validation | Complete output |
+
+All phases synchronous. No async pipeline.
+
+---
+
+## 8. Deterministic Design Principles
+
+| Principle | Enforcement |
+|-----------|-------------|
+| Simplicity first | Start simple; add complexity ONLY when proven necessary |
+| Context discovery | Structured questions by project classification |
+| ADR format | Fixed 6-section format: title, status, context, options, decision, consequences |
+| Pattern routing | Decision trees based on scale + constraints (see pattern-selection.md) |
+| Validation checklist | 6 items: requirements understood, constraints identified, trade-offs analyzed, simpler alternatives considered, ADRs written, team expertise matches |
+| Example types | 3 fixed: MVP (minimal), SaaS (multi-tenant), Enterprise (complex) |
+
+---
+
+## 9. State & Idempotency Model
+
+Stateless. Fully idempotent. No persistent state.
+
+---
+
+## 10. Failure Handling Strategy
+
+| Failure Class | Behavior | Caller Recovery |
+|---------------|----------|-----------------|
+| Unknown project type | Return `ERR_UNKNOWN_PROJECT_TYPE` | Specify mvp, saas, or enterprise |
+| Missing decision topic | Return `ERR_MISSING_TOPIC` | Provide decision topic for trade-off |
+| Invalid request type | Return `ERR_INVALID_REQUEST_TYPE` | Use supported type |
+
+**Invariant:** Every failure returns a structured error. No partial architecture guidance.
+
+---
+
+## 11. Error Taxonomy
+
+| Code | Category | Recoverable | Description |
+|------|----------|-------------|-------------|
+| `ERR_INVALID_REQUEST_TYPE` | Validation | No | Request type not supported |
+| `ERR_UNKNOWN_PROJECT_TYPE` | Validation | Yes | Project type not one of 3 |
+| `ERR_MISSING_TOPIC` | Validation | Yes | Trade-off analysis requires topic |
+| `ERR_UNKNOWN_SCALE` | Validation | Yes | Scale not startup, growth, or enterprise |
+
+---
+
+## 12. Timeout & Retry Policy
+
+| Parameter | Default | Maximum | Rationale |
+|-----------|---------|---------|-----------|
+| Decision generation | N/A | N/A | Synchronous; < 50ms |
+| Internal retries | Zero | Zero | Deterministic output |
+
+---
+
+## 13. Observability & Logging Schema
+
+### Log Entry Format
+
+```json
+{
+  "trace_id": "uuid",
+  "skill_name": "system-design",
+  "contract_version": "2.0.0",
+  "execution_id": "uuid",
+  "timestamp": "ISO-8601",
+  "request_type": "string",
+  "project_type": "string|null",
+  "scale": "string|null",
+  "pattern_recommended": "string|null",
+  "validation_passed": "boolean|null",
+  "status": "success|error",
+  "error_code": "string|null",
+  "duration_ms": "number"
+}
+```
+
+### Required Log Points
+
+| Event | Log Level | Fields |
+|-------|-----------|--------|
+| Context classified | INFO | project_type, scale |
+| Pattern recommended | INFO | pattern_recommended, rationale |
+| ADR generated | INFO | decision_topic, status |
+| Validation complete | INFO | checklist_passed, items_count |
+| Decision failed | ERROR | error_code, message |
+
+### Metrics
+
+| Metric | Type | Unit |
+|--------|------|------|
+| `systemdesign.decision.duration` | Histogram | ms |
+| `systemdesign.project_type.distribution` | Counter | per type |
+| `systemdesign.pattern.distribution` | Counter | per pattern |
+| `systemdesign.validation.pass_rate` | Gauge | percentage |
+
+---
+
+## 14. Security & Trust Model
+
+### Data Handling
+
+- System Design processes project types, scales, and constraints only.
+- No credentials, no PII, no infrastructure access.
+- No network calls, no file modifications, no code execution.
+
+---
+
+## 15. Scalability Model
+
+| Dimension | Constraint | Mitigation |
+|-----------|-----------|------------|
+| Throughput | CPU-bound decision tree | < 50ms; scales linearly |
+| Concurrency | Stateless invocations | Unlimited parallel |
+| Memory per invocation | < 1 MB | No accumulation |
+| Network | Zero network calls | No external dependency |
+
+---
+
+## 16. Concurrency Model
+
+Fully parallel. No shared state. No coordination required.
+
+---
+
+## 17. Resource Lifecycle Management
+
+All resources scoped to invocation. No persistent handles.
+
+---
+
+## 18. Performance Constraints
+
+| Operation | P50 Target | P99 Target | Hard Limit |
+|-----------|-----------|-----------|------------|
+| Context discovery | < 2 ms | < 5 ms | 20 ms |
+| Pattern selection | < 2 ms | < 5 ms | 20 ms |
+| Trade-off analysis | < 5 ms | < 15 ms | 50 ms |
+| Validation | < 2 ms | < 5 ms | 20 ms |
+| Full review | < 15 ms | < 40 ms | 50 ms |
+| Output size | ≤ 5,000 chars | ≤ 10,000 chars | 15,000 chars |
+
+---
+
+## 19. Operational Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| New architecture patterns | Medium | Outdated decision trees | Annual pattern review |
+| Cloud provider changes | Low | Invalid scaling guidance | Track major cloud updates |
+| Team ignores ADRs | Medium | Undocumented decisions | Enforce ADR in PR process |
+| Over-engineering bias | Medium | Complexity debt | Simplicity-first validation check |
+
+---
+
+## 20. Compliance with skill-design-guide.md
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| YAML frontmatter complete | ✅ | name, description, metadata with category, version, triggers, coordinates_with, success_metrics |
+| SKILL.md < 200 lines | ✅ | Entry point under 200 lines |
+| Prerequisites documented | ✅ | No external dependencies |
+| When to Use section | ✅ | Situation-based routing table |
+| Core content matches skill type | ✅ | Expert type: context discovery, trade-off analysis, pattern selection |
+| Troubleshooting section | ✅ | Anti-patterns table |
+| Related section | ✅ | Cross-links to api-architect, data-modeler |
+| Content Map for multi-file | ✅ | Links to 5 reference files + engineering-spec.md |
+| Contract versioning | ✅ | contract_version, backward_compatibility, breaking_changes |
+| Compliance matrix structured | ✅ | This table with ✅/❌ + evidence |
+
+---
+
+## 21. Production Readiness Checklist
+
+| Category | Check | Status |
+|----------|-------|--------|
+| **Functionality** | Context discovery with project classification | ✅ |
+| **Functionality** | Trade-off analysis with ADR format | ✅ |
+| **Functionality** | Pattern selection with decision trees | ✅ |
+| **Functionality** | Architecture validation (6-item checklist) | ✅ |
+| **Functionality** | 3 example types (MVP, SaaS, Enterprise) | ✅ |
+| **Contracts** | Input/output/error schemas in pseudo-schema format | ✅ |
+| **Contracts** | Contract versioning with semver | ✅ |
+| **Failure** | Error taxonomy with 4 categorized codes | ✅ |
+| **Failure** | Zero internal retries | ✅ |
+| **Determinism** | Fixed ADR format, fixed checklist, fixed decision trees | ✅ |
+| **Security** | No credentials, no infrastructure, no code | ✅ |
+| **Observability** | Structured log schema with 5 mandatory fields | ✅ |
+| **Observability** | 4 metrics defined | ✅ |
+| **Performance** | P50/P99 targets for all operations | ✅ |
+| **Compliance** | All skill-design-guide.md sections mapped with evidence | ✅ |
+
+---
+
+⚡ PikaKit v3.9.134

package/.agent/skills/system-design/rules/examples.md

@@ -0,0 +1,180 @@
+---
+name: examples
+description: Architecture examples — MVP, SaaS, Enterprise with decisions, trade-offs, migration paths, and component diagrams
+---
+
+# Architecture Examples
+
+> Real-world architecture decisions by project type. Each with rationale and migration paths.
+
+---
+
+## Example 1: MVP E-commerce (Solo Developer)
+
+```
+Requirements: <1K users, solo dev, 8 weeks, budget-conscious
+```
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Structure | Monolith | Solo dev, no team coordination needed |
+| Framework | Next.js | Full-stack, fast to ship, Vercel deploy |
+| Data Layer | Prisma direct | Simple CRUD, no over-abstraction |
+| Auth | JWT (simple) | No social login initially |
+| Payment | Stripe Checkout | Hosted, PCI compliant |
+| Database | PostgreSQL | ACID for orders |
+| Hosting | Vercel + Supabase | Free tier, managed |
+
+### Component Diagram
+
+```mermaid
+graph LR
+    Client[Browser] --> Next[Next.js App]
+    Next --> Prisma[Prisma ORM]
+    Prisma --> PG[(PostgreSQL)]
+    Next --> Stripe[Stripe API]
+    Next --> Vercel[Vercel Edge]
+```
+
+### Trade-offs Accepted
+
+| What We Give Up | Why It's OK |
+|-----------------|------------|
+| Independent scaling | Solo dev, <1K users |
+| Repository pattern | Simple CRUD doesn't need it |
+| Social login | Can add OAuth later |
+
+### Migration Triggers
+
+| When | Action |
+|------|--------|
+| Users > 10K | Extract payment service |
+| Team > 3 | Add Repository pattern |
+| Social login needed | Add NextAuth.js / OAuth |
+
+---
+
+## Example 2: SaaS Product (5-10 Developers)
+
+```
+Requirements: 1K-100K users, 5-10 devs, 12+ months, multi-domain
+```
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Structure | Modular Monolith | Team size optimal, clear boundaries |
+| Framework | NestJS | Modular by design, TypeScript |
+| Data Layer | Repository pattern | Testing, flexibility |
+| Domain | Partial DDD | Rich entities, no full aggregates |
+| Auth | OAuth + JWT | Social login, API tokens |
+| Cache | Redis | Session, rate limit, pub/sub |
+| Database | PostgreSQL | Relational, JSON support |
+| Queue | BullMQ (Redis) | Background jobs |
+| Deployment | Docker + GitHub Actions | Reproducible builds |
+
+### Component Diagram
+
+```mermaid
+graph LR
+    Client[Browser/Mobile] --> Gateway[API Gateway]
+    Gateway --> Users[Users Module]
+    Gateway --> Billing[Billing Module]
+    Gateway --> Core[Core Module]
+    Users --> Repo1[User Repository]
+    Core --> Repo2[Core Repository]
+    Repo1 --> PG[(PostgreSQL)]
+    Repo2 --> PG
+    Core --> Redis[(Redis)]
+    Billing --> Stripe[Stripe API]
+```
+
+### Trade-offs Accepted
+
+| What We Give Up | Why It's OK |
+|-----------------|------------|
+| Independent deployment | Monolith coupling acceptable at team size |
+| Full DDD aggregates | No domain experts on team |
+| Event sourcing | Simple state mutations sufficient |
+
+### Migration Triggers
+
+| When | Action |
+|------|--------|
+| Team > 10 | Extract services (billing first) |
+| Domain conflicts | Split bounded contexts |
+| Read perf issues | Add CQRS for read models |
+| Async workloads | Add Kafka/RabbitMQ |
+
+---
+
+## Example 3: Enterprise Platform (100K+ Users)
+
+```
+Requirements: 100K+ users, 10+ devs, multiple domains, 24/7 availability
+```
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Structure | Microservices | Independent scale, team ownership |
+| API Gateway | Kong / AWS API GW | Routing, rate limiting, auth |
+| Domain | Full DDD | Complex business rules |
+| Consistency | Event-driven (eventual) | Decoupled services |
+| Message Bus | Kafka | High throughput, replay |
+| Auth | OAuth + SAML | Enterprise SSO |
+| Database | Polyglot | Right tool per service |
+| CQRS | Selected services | Read/write divergence |
+| Deployment | Kubernetes + Helm | Orchestration at scale |
+
+### Component Diagram
+
+```mermaid
+graph TB
+    Client[Clients] --> GW[API Gateway]
+    GW --> UserSvc[User Service]
+    GW --> OrderSvc[Order Service]
+    GW --> PaySvc[Payment Service]
+    UserSvc --> UserDB[(User DB - PG)]
+    OrderSvc --> OrderDB[(Order DB - PG)]
+    PaySvc --> PayDB[(Payment DB - PG)]
+    OrderSvc --> Kafka[Kafka Bus]
+    PaySvc --> Kafka
+    Kafka --> Analytics[Analytics Service]
+    Analytics --> ClickHouse[(ClickHouse)]
+```
+
+### Operational Requirements
+
+| Concern | Solution |
+|---------|----------|
+| Service mesh | Istio / Linkerd |
+| Distributed tracing | Jaeger / Tempo |
+| Centralized logging | ELK / Loki + Grafana |
+| Circuit breakers | Resilience4j |
+| Secrets management | HashiCorp Vault |
+
+---
+
+## Cross-Tier Comparison
+
+| Aspect | MVP | SaaS | Enterprise |
+|--------|-----|------|-----------|
+| **Complexity** | Low | Medium | Very High |
+| **Time to deploy** | Hours | Days | Weeks |
+| **Ops overhead** | Minimal | Moderate | Significant |
+| **Cost (monthly)** | $0-50 | $100-1K | $5K+ |
+| **Team expertise** | Junior OK | Mid-Senior | Senior + DevOps |
+| **Recovery** | Git revert | Blue/green deploy | Canary + rollback |
+
+---
+
+## 🔗 Related
+
+| File | When to Read |
+|------|-------------|
+| [context-discovery.md](context-discovery.md) | Classify your project |
+| [pattern-selection.md](pattern-selection.md) | Choose patterns |
+| [trade-off-analysis.md](trade-off-analysis.md) | Document decisions |
+
+---
+
+⚡ PikaKit v3.9.134