@wipal/agent-team 1.0.0

package/.claude/skills/domain/architecture/system-design/references/scalability.md

@@ -0,0 +1,303 @@
+# Scalability Strategies
+
+## What is Scalability?
+The ability of a system to handle growing amounts of work by adding resources.
+
+## Types of Scaling
+
+### Vertical Scaling (Scale Up)
+```
+Before:                    After:
+┌──────────┐              ┌──────────────────┐
+│  4 CPU   │              │     64 CPU       │
+│  16 GB   │     ──▶      │     256 GB       │
+│  1 TB    │              │     16 TB        │
+└──────────┘              └──────────────────┘
+
+Pros:
+- Simple (no code changes)
+- Strong consistency (single node)
+- Lower latency (no network)
+
+Cons:
+- Hardware limits
+- Expensive at scale
+- Single point of failure
+- Downtime for upgrades
+```
+
+### Horizontal Scaling (Scale Out)
+```
+Before:                    After:
+┌──────────┐              ┌──────────┐
+│  Server  │              │ Server 1 │
+│          │     ──▶      ├──────────┤
+└──────────┘              │ Server 2 │
+                          ├──────────┤
+                          │ Server 3 │
+                          └──────────┘
+
+Pros:
+- Nearly unlimited scale
+- Commodity hardware
+- No single point of failure
+- Incremental growth
+
+Cons:
+- Complexity (distributed)
+- Network latency
+- Data consistency challenges
+- Load balancing needed
+```
+
+## Load Balancing
+
+### Algorithms
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Load Balancer                        │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
+│  │ Server1 │  │ Server2 │  │ Server3 │  │ Server4 │   │
+│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+
+Strategies:
+1. Round Robin - Rotate through servers
+2. Weighted Round Robin - More weight to stronger servers
+3. Least Connections - Route to least busy
+4. IP Hash - Same IP to same server (session affinity)
+5. Least Response Time - Route to fastest responding
+6. Random - Distribute randomly
+```
+
+### Health Checks
+```
+Active Health Checks:
+- LB periodically checks endpoint
+- Remove unhealthy servers from pool
+- Add back when healthy
+
+Passive Health Checks:
+- Monitor real requests
+- Track failure rates
+- Circuit breaker pattern
+```
+
+## Database Scaling
+
+### Read Replicas
+```
+                ┌─────────────┐
+                │   Primary   │
+                │  (Writes)   │
+                └──────┬──────┘
+                       │
+         ┌─────────────┼─────────────┐
+         │             │             │
+         ▼             ▼             ▼
+   ┌──────────┐ ┌──────────┐ ┌──────────┐
+   │ Replica1 │ │ Replica2 │ │ Replica3 │
+   │ (Reads)  │ │ (Reads)  │ │ (Reads)  │
+   └──────────┘ └──────────┘ └──────────┘
+
+Considerations:
+- Replication lag
+- Read-after-write consistency
+- Connection routing
+```
+
+### Sharding (Horizontal Partitioning)
+```
+Sharding Strategies:
+
+1. Range-based:
+   Shard 1: Users 1-1,000,000
+   Shard 2: Users 1,000,001-2,000,000
+   Shard 3: Users 2,000,001-3,000,000
+
+   Pros: Range queries efficient
+   Cons: Hot spots, uneven distribution
+
+2. Hash-based:
+   Shard = hash(user_id) % num_shards
+
+   Pros: Even distribution
+   Cons: Range queries inefficient, resharding complex
+
+3. Directory-based:
+   Lookup table: user_id → shard
+
+   Pros: Flexible, easy resharding
+   Cons: Lookup overhead, single point of failure
+
+4. Geographic:
+   Shard by location (US, EU, Asia)
+
+   Pros: Compliance, latency
+   Cons: Uneven distribution possible
+```
+
+### Vertical Partitioning
+```
+Split by functionality:
+
+┌─────────────────┐     ┌─────────────────┐
+│   Users DB      │     │   Orders DB     │
+├─────────────────┤     ├─────────────────┤
+│ id              │     │ id              │
+│ email           │     │ user_id         │
+│ password_hash   │     │ total           │
+│ created_at      │     │ status          │
+└─────────────────┘     │ created_at      │
+                        └─────────────────┘
+
+Benefits:
+- Smaller tables, better cache
+- Isolated scaling
+- Security (sensitive data separate)
+```
+
+## Caching Strategies
+
+### Cache Patterns
+```
+1. Cache-aside (Lazy Loading)
+   ┌───────┐     ┌───────┐     ┌───────┐
+   │Client │────▶│Cache  │────▶│  DB   │
+   └───────┘     └───────┘     └───────┘
+                     │
+                     │ miss
+                     ▼
+   Application code manages cache
+   On read: Check cache → if miss, read DB → populate cache
+   On write: Update DB → invalidate cache
+
+2. Write-through
+   ┌───────┐     ┌───────┐     ┌───────┐
+   │Client │────▶│Cache  │────▶│  DB   │
+   └───────┘     └───────┘     └───────┘
+                     │
+                     │ always write both
+                     ▼
+   Write to cache AND DB synchronously
+   Data always consistent
+
+3. Write-behind (Write-back)
+   ┌───────┐     ┌───────┐     ┌───────┐
+   │Client │────▶│Cache  │────▶│  DB   │
+   └───────┘     └───────┘     └───────┘
+                     │
+                     │ async write to DB
+                     ▼
+   Write to cache, async write to DB
+   Higher throughput, risk of data loss
+
+4. Refresh-ahead
+   Proactively refresh before expiration
+   Good for predictable access patterns
+```
+
+### Cache Eviction Policies
+```
+LRU (Least Recently Used):
+- Evict item not accessed longest
+- Good for temporal locality
+
+LFU (Least Frequently Used):
+- Evict item accessed least often
+- Good for popularity-based access
+
+FIFO (First In First Out):
+- Simple queue-based eviction
+- Less optimal but simple
+
+TTL (Time To Live):
+- Expire after time period
+- Good for stale data prevention
+```
+
+## Queue-Based Scaling
+
+### Message Queue Pattern
+```
+┌─────────┐     ┌─────────────┐     ┌─────────┐
+│Producer │────▶│   Queue     │────▶│Consumer │
+└─────────┘     │             │     └─────────┘
+                │ ┌─┬─┬─┬─┬─┐ │
+                │ └─┴─┴─┴─┴─┘ │
+                └─────────────┘
+
+Benefits:
+- Decouple producers from consumers
+- Handle traffic spikes (queue absorbs)
+- Scale consumers independently
+- Asynchronous processing
+
+Examples:
+- RabbitMQ, Kafka, SQS, Redis Streams
+```
+
+### Backpressure
+```
+When consumers can't keep up:
+
+1. Drop (oldest/newest/random)
+2. Block producer
+3. Shed load (reject new requests)
+4. Scale consumers
+5. Buffer (temporary solution)
+```
+
+## Autoscaling
+
+### Metrics for Scaling
+```
+Scale Out Triggers:
+- CPU > 70% for 5 minutes
+- Memory > 80% for 5 minutes
+- Request queue depth > 100
+- Response time > 500ms
+- Custom business metrics
+
+Scale In Triggers:
+- CPU < 30% for 15 minutes
+- Memory < 40% for 15 minutes
+- Queue depth < 10
+```
+
+### Scaling Strategies
+```
+Reactive:
+- Respond to current metrics
+- May be too slow for spikes
+
+Predictive:
+- Use ML to predict load
+- Scale before traffic arrives
+- Requires historical data
+
+Scheduled:
+- Scale at known times
+- Black Friday, end of month
+- Simple and predictable
+```
+
+## Best Practices
+
+### Design for Scale
+1. **Stateless services** - No server affinity
+2. **Idempotent operations** - Safe to retry
+3. **Async where possible** - Don't block
+4. **Partition data** - Enable horizontal scaling
+5. **Cache aggressively** - Reduce DB load
+6. **Use CDNs** - Offload static content
+
+### Avoid
+1. **Distributed transactions** - Use sagas
+2. **Joins across shards** - Denormalize
+3. **Synchronous dependencies** - Add queues
+4. **Locks on hot data** - Use optimistic locking
+5. **Single points of failure** - Replicate everything

package/.claude/skills/domain/architecture/tech-selection/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: tech-selection
+description: |
+  Use when evaluating and selecting technologies for a project.
+  Provides frameworks for objective comparison and decision making.
+version: 1.0.0
+category: architecture
+tags:
+  - technology
+  - evaluation
+  - selection
+  - decision-framework
+dependencies:
+  - adr-writing
+references:
+  - references/evaluation-framework.md
+  - references/build-vs-buy.md
+  - references/tech-radar.md
+---
+
+# Technology Selection
+
+## Core Principle
+**Choose technology based on requirements, not trends. Fit the tool to the problem.**
+
+## When to Use This Skill
+
+### Trigger Conditions
+- Starting a new project
+- Evaluating alternatives for existing system
+- Replacing deprecated technology
+- Team wants to adopt new technology
+
+### Keywords
+- "choose technology"
+- "evaluate options"
+- "technology selection"
+- "which framework"
+- "build vs buy"
+
+## Evaluation Framework
+
+### Step 1: Define Requirements
+```
+Functional Requirements:
+- What must the technology do?
+- What features are required?
+- What integrations needed?
+
+Non-Functional Requirements:
+- Performance requirements
+- Scalability needs
+- Security requirements
+- Compliance requirements
+
+Constraints:
+- Budget constraints
+- Timeline constraints
+- Team expertise
+- Infrastructure constraints
+```
+
+### Step 2: Create Evaluation Matrix
+```
+| Criteria       | Weight | Tech A | Tech B | Tech C |
+|----------------|--------|--------|--------|--------|
+| Performance    | 20%    | 4/5    | 5/5    | 3/5    |
+| Scalability    | 15%    | 5/5    | 4/5    | 4/5    |
+| Developer XP   | 15%    | 4/5    | 3/5    | 5/5    |
+| Documentation  | 10%    | 5/5    | 4/5    | 4/5    |
+| Community      | 15%    | 4/5    | 5/5    | 3/5    |
+| Cost           | 15%    | 3/5    | 4/5    | 5/5    |
+| Risk           | 10%    | 4/5    | 4/5    | 3/5    |
+|----------------|--------|--------|--------|--------|
+| Weighted Score | 100%   | 4.05   | 4.10   | 3.85   |
+```
+
+### Step 3: Evaluate Options
+```
+For each technology, assess:
+1. Maturity - How long has it existed?
+2. Adoption - Who else uses it?
+3. Support - Commercial/community support?
+4. Documentation - Quality and completeness?
+5. Learning curve - Time to proficiency?
+6. Ecosystem - Plugins, integrations?
+7. Future outlook - Active development?
+```
+
+### Step 4: Prototype/POC
+```
+If uncertain:
+1. Build small prototype
+2. Test critical requirements
+3. Involve team members
+4. Document findings
+5. Time-box the evaluation
+```
+
+### Step 5: Document Decision
+```
+Write ADR with:
+- Evaluated options
+- Scoring rationale
+- Final decision
+- Consequences
+```
+
+## Decision Criteria
+
+### Technology Fit Criteria
+```
+1. Problem Fit
+   - Does it solve our problem?
+   - Is it over/under-engineered?
+
+2. Team Fit
+   - Does team have expertise?
+   - Can team learn it quickly?
+   - Is talent available to hire?
+
+3. Organization Fit
+   - Does it align with tech strategy?
+   - Does it fit existing infrastructure?
+   - Does it meet compliance needs?
+
+4. Ecosystem Fit
+   - Integration with existing tools?
+   - Community support?
+   - Long-term viability?
+```
+
+## Build vs Buy Decision
+
+### When to Build
+```
+✅ Core competitive advantage
+✅ Unique requirements
+✅ Full control needed
+✅ No suitable solution exists
+✅ Long-term strategic value
+✅ Team has expertise and time
+```
+
+### When to Buy
+```
+✅ Commodity functionality
+✅ Faster time to market needed
+✅ Team lacks expertise
+✅ Maintenance burden too high
+✅ Solution exists and is mature
+✅ Not core to business
+```
+
+## Common Evaluation Pitfalls
+
+### Avoid
+```
+❌ Resume-driven development
+❌ Hype-driven decisions
+❌ Not involving team
+❌ Skipping POC for critical choices
+❌ Ignoring operational concerns
+❌ Underestimating learning curve
+❌ Ignoring vendor lock-in
+❌ Not considering total cost
+```
+
+## Output
+
+When using this skill:
+1. **Evaluation Matrix** - Scored comparison
+2. **ADR** - Documented decision
+3. **POC Report** - If prototype was built
+4. **Migration Plan** - If replacing existing tech
+
+## Rules
+
+### DO
+- ✅ Start with requirements, not solutions
+- ✅ Evaluate at least 2-3 options
+- ✅ Include team in evaluation
+- ✅ Consider total cost of ownership
+- ✅ Build POC for risky choices
+- ✅ Document decision with ADR
+
+### DON'T
+- ❌ Choose based on trends/hype
+- ❌ Make decision alone
+- ❌ Ignore existing expertise
+- ❌ Forget operational costs
+- ❌ Skip documentation