bobs-workshop 0.3.3 → 3.1.0

package/src/skills/api-patterns/SKILL.md

@@ -0,0 +1,376 @@
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+---
+
+# API Design Patterns
+
+> Design principles for building scalable, maintainable APIs.
+
+---
+
+## API Style Selection
+
+### When to Use Each Style
+
+| API Style | Best For | Pros | Cons |
+|-----------|-----------|-------|-------|
+| **REST** | Public APIs, general purpose, caching important | Simple, standard, cacheable | Over-fetching/under-fetching, multiple requests |
+| **GraphQL** | Complex data needs, mobile clients, flexible queries | Single request, no over-fetching | Complex, caching harder, learning curve |
+| **tRPC** | Full-stack TypeScript, internal APIs | Type-safe, minimal boilerplate | TypeScript-only, less standard |
+| **gRPC** | Internal microservices, high performance | Fast, streaming, typed | Protocol buffers, HTTP/2 required |
+
+### Selection Framework
+
+```markdown
+## Decision: Which API Style?
+
+### Questions
+1. **Public or Internal?** (Public → REST/GraphQL, Internal → tRPC/gRPC)
+2. **Client flexibility needed?** (High → GraphQL, Low → REST)
+3. **Type safety critical?** (Yes → tRPC/gRPC, No → REST/GraphQL)
+4. **Performance critical?** (Yes → gRPC, No → REST)
+5. **Team expertise?** (What does team know?)
+
+### Decision Matrix
+| Factor | REST | GraphQL | tRPC | gRPC |
+|--------|-------|----------|-------|-------|
+| Simplicity | ✅ High | ⚠️ Medium | ✅ High | ⚠️ Medium |
+| Type Safety | ❌ Low | ⚠️ Medium | ✅ High | ✅ High |
+| Performance | ⚠️ Medium | ⚠️ Medium | ✅ High | ✅ High |
+| Ecosystem | ✅ Large | ✅ Large | ⚠️ Growing | ✅ Large |
+| Caching | ✅ Easy | ❌ Hard | ❌ Hard | ⚠️ Medium |
+```
+
+---
+
+## REST API Best Practices
+
+### Resource Naming
+
+| Rule | Example |
+|------|---------|
+| **Use nouns, not verbs** | ✅ `/users`, ❌ `/getUsers` |
+| **Plural nouns** | ✅ `/users`, ❌ `/user` |
+| **Nest resources** | ✅ `/users/123/posts`, ❌ `/posts?user=123` |
+| **Lowercase with hyphens** | ✅ `/user-preferences`, ❌ `/userPreferences` |
+
+### HTTP Methods
+
+| Method | Use | Safe | Idempotent |
+|--------|-----|-------|------------|
+| **GET** | Read resources | ✅ Yes | ✅ Yes |
+| **POST** | Create resource | ❌ No | ❌ No |
+| **PUT** | Replace resource | ❌ No | ✅ Yes |
+| **PATCH** | Partial update | ❌ No | ❌ No |
+| **DELETE** | Delete resource | ❌ No | ✅ Yes |
+
+### Status Codes
+
+| Code | Meaning | When to Use |
+|------|----------|-------------|
+| **200 OK** | Success | GET, PUT, DELETE successful |
+| **201 Created** | Resource created | POST successful |
+| **204 No Content** | Success, no body | DELETE successful |
+| **400 Bad Request** | Invalid input | Client error |
+| **401 Unauthorized** | Not authenticated | Missing/expired token |
+| **403 Forbidden** | No permission | Authenticated but not allowed |
+| **404 Not Found** | Resource missing | Invalid ID |
+| **409 Conflict** | Conflict | Duplicate resource |
+| **422 Unprocessable** | Validation error | Data validation failed |
+| **429 Too Many** | Rate limited | Exceeded rate limit |
+| **500 Internal Server** | Server error | Bug on server |
+
+### Request/Response Format
+
+**Request:**
+```json
+{
+  "user": {
+    "name": "John",
+    "email": "john@example.com"
+  }
+}
+```
+
+**Response (Success):**
+```json
+{
+  "data": {
+    "user": {
+      "id": "123",
+      "name": "John",
+      "email": "john@example.com",
+      "createdAt": "2024-01-01T00:00:00Z"
+    }
+  }
+}
+```
+
+**Response (Error):**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid email address",
+    "details": [
+      {
+        "field": "email",
+        "message": "Must be a valid email"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Pagination
+
+### Pagination Strategies
+
+| Strategy | Best For | Pros | Cons |
+|-----------|-----------|-------|-------|
+| **Offset/Limit** | Simple apps, small datasets | Simple, standard | Slow with large offsets |
+| **Cursor-based** | Infinite scroll, large datasets | Fast, efficient | No random access |
+| **Page-based** | Paginated lists | Simple | Gaps on deletes |
+
+### Offset/Limit (Simple)
+
+```http
+GET /users?page=1&limit=20
+```
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100,
+    "totalPages": 5
+  }
+}
+```
+
+### Cursor-based (Efficient)
+
+```http
+GET /users?limit=20&cursor=abc123
+```
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "hasNext": true,
+    "nextCursor": "def456"
+  }
+}
+```
+
+---
+
+## Versioning
+
+### Versioning Strategies
+
+| Strategy | Best For | Example |
+|-----------|-----------|---------|
+| **URL Path** | Multiple versions supported | `/v1/users`, `/v2/users` |
+| **Query Parameter** | Testing, feature flags | `/users?version=v2` |
+| **Header** | API gateway routing | `Accept: application/vnd.api.v2+json` |
+
+### Best Practice: URL Path
+
+```
+/api/v1/users
+/api/v2/users
+```
+
+**Guidelines:**
+- Use URL path versioning (most standard)
+- Support previous version for 6-12 months
+- Deprecate with warning header: `X-Deprecated: true`
+
+---
+
+## Authentication & Authorization
+
+### Auth Strategies
+
+| Strategy | Best For | Tools |
+|-----------|-----------|--------|
+| **JWT** | Stateless, scalable | NextAuth, Auth0, custom |
+| **Session** | Traditional web apps | Express-session, Passport |
+| **API Keys** | Service-to-service | Custom, cloud provider |
+| **OAuth2** | Third-party login | NextAuth, Auth0 |
+
+### Implementation Pattern
+
+```typescript
+// Middleware example
+function authMiddleware(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  if (!token) return res.status(401).json({ error: 'Unauthorized' });
+
+  const decoded = verifyToken(token);
+  req.user = decoded;
+  next();
+}
+```
+
+---
+
+## Error Handling
+
+### Error Response Format
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ],
+    "requestId": "req_abc123"
+  }
+}
+```
+
+### Error Codes
+
+| Category | Codes | Format |
+|----------|--------|--------|
+| **Validation** | VALIDATION_ERROR, INVALID_INPUT | CAPITAL_SNAKE_CASE |
+| **Auth** | UNAUTHORIZED, FORBIDDEN, TOKEN_EXPIRED | CAPITAL_SNAKE_CASE |
+| **Not Found** | RESOURCE_NOT_FOUND, USER_NOT_FOUND | CAPITAL_SNAKE_CASE |
+| **Server** | INTERNAL_ERROR, DATABASE_ERROR | CAPITAL_SNAKE_CASE |
+
+---
+
+## Rate Limiting
+
+### Rate Limiting Strategies
+
+| Strategy | Best For | Pros | Cons |
+|-----------|-----------|-------|-------|
+| **Fixed Window** | Simple rate limiting | Simple, but bursty |
+| **Sliding Window** | Smooth rate limiting | Accurate, but complex |
+| **Token Bucket** | API rate limiting | Smooth, flexible |
+| **Leaky Bucket** | Data rate limiting | Constant rate |
+
+### Response Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640995200
+```
+
+---
+
+## Documentation
+
+### API Documentation Tools
+
+| Tool | Best For | Features |
+|------|-----------|----------|
+| **OpenAPI (Swagger)** | REST APIs | Auto-generated docs, testing |
+| **GraphQL Playground** | GraphQL APIs | Interactive queries, schema |
+| **tRPC Playground** | tRPC APIs | Type-safe testing |
+| **Postman** | Manual testing | Collections, environments |
+
+### Documentation Must-Haves
+
+- [ ] Endpoint URLs and methods
+- [ ] Request/response examples
+- [ ] Authentication requirements
+- [ ] Error codes and meanings
+- [ ] Rate limits
+- [ ] Version information
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **alice (architect)** agent during PLAN phase and **bob-eng (engineer)** during BUILD phase.
+
+### MANUAL Integration
+
+Add API section to MANUAL:
+```markdown
+## 🏗️ Architecture Analysis
+
+### API Design
+
+#### API Style Selection
+- **Style:** [REST / GraphQL / tRPC / gRPC]
+- **Rationale:** [Why this style?]
+- **Framework:** [Express / Fastify / Next.js API / tRPC / etc.]
+
+#### API Structure
+
+**Endpoints:**
+| Method | Endpoint | Description | Auth |
+|--------|-----------|-------------|-------|
+| GET | /api/v1/users | List users | Required |
+| GET | /api/v1/users/:id | Get user | Required |
+| POST | /api/v1/users | Create user | Required |
+| PUT | /api/v1/users/:id | Update user | Required |
+| DELETE | /api/v1/users/:id | Delete user | Required |
+
+#### Authentication
+- **Strategy:** [JWT / Session / OAuth2 / API Keys]
+- **Middleware:** [Custom / NextAuth / Passport / etc.]
+- **Token Expiry:** [1 hour / 24 hours / 7 days]
+
+#### Rate Limiting
+- **Strategy:** [Fixed Window / Sliding Window / Token Bucket]
+- **Limits:** [100 requests per 15 minutes]
+- **Headers:** `X-RateLimit-Limit`, `X-RateLimit-Remaining`
+
+#### Error Handling
+- **Format:** Standard error object with code, message, details
+- **Codes:** VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, INTERNAL_ERROR
+```
+
+### Implementation Tasks
+
+```markdown
+#### API-001: User Endpoints
+- [ ] Create GET /api/v1/users → Verify: Returns paginated list
+- [ ] Create GET /api/v1/users/:id → Verify: Returns single user
+- [ ] Create POST /api/v1/users → Verify: Creates user, returns 201
+- [ ] Add auth middleware → Verify: Protects endpoints
+- [ ] Add validation → Verify: Returns 422 on invalid input
+
+#### API-002: Error Handling
+- [ ] Create error middleware → Verify: Returns standard error format
+- [ ] Add error codes → Verify: All errors have codes
+- [ ] Add request ID → Verify: Each request has unique ID
+```
+
+### Testing Strategy
+
+```markdown
+#### API-TEST-001: API Tests
+- [ ] Test all endpoints → Verify: Return correct status codes
+- [ ] Test authentication → Verify: Unauthenticated requests return 401
+- [ ] Test authorization → Verify: Unauthorized requests return 403
+- [ ] Test validation → Verify: Invalid input returns 422
+- [ ] Test rate limiting → Verify: Exceeding limit returns 429
+```
+
+### Handoff Format
+
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 alice: API designed - REST with JWT auth
+🤝 alice → bob-eng: API spec ready, proceeding to implementation
+```

package/src/skills/architecture/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: architecture
+description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation.
+metadata:
+  recommended_for: alice
+  category: architecture
+---
+
+# Architecture Decision Framework
+
+> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
+| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
+| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
+| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
+| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |
+
+---
+
+## 🔗 Related Skills
+
+| Skill | Use For |
+|-------|---------|
+| `@skills/database-design` | Database schema design |
+| `@skills/api-patterns` | API design patterns |
+| `@skills/deployment-procedures` | Deployment architecture |
+
+---
+
+## Core Principle
+
+**"Simplicity is the ultimate sophistication."**
+
+- Start simple
+- Add complexity ONLY when proven necessary
+- You can always add patterns later
+- Removing complexity is MUCH harder than adding it
+
+---
+
+## Validation Checklist
+
+Before finalizing architecture:
+
+- [ ] Requirements clearly understood
+- [ ] Constraints identified
+- [ ] Each decision has trade-off analysis
+- [ ] Simpler alternatives considered
+- [ ] ADRs written for significant decisions
+- [ ] Team expertise matches chosen patterns
+
+---
+
+## Architecture Decision Record (ADR) Template
+
+```markdown
+# ADR-[number]: [Title]
+
+## Status
+- [ ] Proposed
+- [ ] Accepted
+- [ ] Deprecated
+- [ ] Superseded by [ADR-number]
+
+## Context
+- What is the issue we're facing?
+- What is the problem we're trying to solve?
+- What are the constraints we're working with?
+
+## Decision
+- What did we decide?
+- What is the solution?
+- What pattern/approach did we choose?
+
+## Consequences
+- **Positive**: What are the benefits?
+- **Negative**: What are the drawbacks?
+- **Risks**: What could go wrong?
+- **Alternatives considered**: What did we NOT choose and why?
+
+## References
+- Links to relevant documentation
+- Links to similar decisions
+- Links to external resources
+```
+
+---
+
+## Trade-off Analysis Framework
+
+```markdown
+## Decision: [What are we deciding?]
+
+### Options
+| Option | Description | Pros | Cons | Complexity | Time |
+|--------|-------------|-------|-------|------------|------|
+| A | [Description] | [+] | [-] | Low/Med/High | Fast/Med/Slow |
+| B | [Description] | [+] | [-] | Low/Med/High | Fast/Med/Slow |
+
+### Criteria
+- Performance requirements
+- Development time
+- Maintainability
+- Team expertise
+- Scalability needs
+- Budget constraints
+
+### Decision
+**Chosen:** [Option A/B]
+**Rationale:**
+- Primary driver: [Reason]
+- Secondary drivers: [Reasons]
+- Trade-offs accepted: [What we're giving up]
+
+### Success Metrics
+- [ ] How will we measure success?
+- [ ] What indicates this was the right choice?
+```
+
+---
+
+## Common Architectural Patterns
+
+### When to Use Each Pattern
+
+| Pattern | Best For | Complexity | Scalability |
+|---------|-----------|-------------|--------------|
+| **Monolith** | Small teams, rapid development | Low | Limited |
+| **Modular Monolith** | Medium teams, growing complexity | Medium | Good |
+| **Microservices** | Large teams, multiple domains | High | Excellent |
+| **Serverless** | Event-driven, variable load | Medium | Auto-scales |
+| **Event-Driven** | Async processing, loose coupling | High | Excellent |
+
+### Pattern Selection Questions
+
+1. **Team Size**: How many developers? (Small → Monolith, Large → Microservices)
+2. **Complexity**: How many domains? (Few → Monolith, Many → Services)
+3. **Load**: Expected traffic? (Low → Monolith, High → Scaled)
+4. **Time to Market**: How fast do we need to ship? (Fast → Monolith, Slower → Services)
+
+---
+
+## Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Start with microservices | Start with monolith, split when needed |
+| Use complex patterns because "cool" | Use simplest solution that works |
+| Ignore team expertise | Match patterns to team's skills |
+| Make premature optimizations | Optimize when you have data |
+| Skip ADR documentation | Document significant decisions |
+| Choose without trade-offs | Always analyze alternatives |
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **alice (architect)** agent during PLAN phase.
+
+### MANUAL Integration
+
+Add architecture section to MANUAL:
+```markdown
+## 🏗️ Architecture Analysis
+
+### Project Classification
+- **Type:** [MVP / SaaS / Enterprise / Internal Tool]
+- **Scale:** [Small / Medium / Large]
+- **Team:** [Solo / Small team / Large team]
+- **Constraints:** [Technical / Time / Budget / Legal]
+
+### Architecture Decisions
+
+| Decision | ADR # | Pattern | Rationale | Trade-offs |
+|----------|---------|----------|------------|-------------|
+| [Tech Stack] | ADR-001 | [Pattern] | [Why] | [Accepted] |
+| [Database] | ADR-002 | [Pattern] | [Why] | [Accepted] |
+| [API Design] | ADR-003 | [Pattern] | [Why] | [Accepted] |
+
+### System Components
+
+```
+[Component Diagram]
+┌─────────────┐      ┌─────────────┐
+│   Frontend  │─────▶│    API      │
+└─────────────┘      └─────────────┘
+                            │
+                            ▼
+                     ┌─────────────┐
+                     │  Database   │
+                     └─────────────┘
+```
+
+### Technology Stack
+- **Frontend:** [Framework, Language, Libraries]
+- **Backend:** [Framework, Language, Runtime]
+- **Database:** [Type, ORM, Migration Tool]
+- **Infrastructure:** [Cloud, CI/CD, Monitoring]
+```
+
+### ADR Documentation
+
+For each significant decision, create ADR:
+```markdown
+## ADR-001: Choose PostgreSQL as Primary Database
+
+### Context
+- Need for relational data model
+- ACID compliance required for transactions
+- Team has PostgreSQL experience
+
+### Decision
+- Use PostgreSQL 15+
+- Use Prisma as ORM
+- Use Liquibase for migrations
+
+### Consequences
+- **Positive**: Team expertise, ACID guarantees, rich ecosystem
+- **Negative**: Requires maintenance, scaling requires planning
+- **Risks**: Connection pooling, index optimization
+- **Alternatives Considered**: MySQL (less familiar), MongoDB (not relational)
+
+### Success Metrics
+- [ ] Queries < 100ms for 95th percentile
+- [ ] Supports 10x traffic growth without major changes
+```
+
+### Validation Checklist
+
+Before proceeding to implementation:
+- [ ] Requirements clearly understood
+- [ ] Constraints identified
+- [ ] Each decision has trade-off analysis
+- [ ] Simpler alternatives considered
+- [ ] ADRs written for significant decisions
+- [ ] Team expertise matches chosen patterns
+
+### Handoff Format
+
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 alice: Architecture complete - 5 ADRs documented
+🤝 alice → bob-eng: MANUAL ready - proceeding to BUILD phase
+```
+
+---
+
+## Design Patterns
+
+When design tradeoffs arise:
+
+1. **Compare architecture patterns** - Evaluate each option against requirements
+2. **Suggest modular compositions** - Prefer loose coupling, high cohesion
+3. **Evaluate coupling/cohesion** - Minimize dependencies, group related concerns
+
+### Design Decision Framework
+
+| Question | What to Evaluate |
+|----------|------------------|
+| What are the components? | Identify clear boundaries |
+| How do they communicate? | Define interfaces and contracts |
+| What are the dependencies? | Minimize and make explicit |
+| How to handle failure? | Design for resilience |

package/src/skills/bobs-workshop/performance/icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="#10b981" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M22 12h-4l-3 9L9 3l-3 9H2"/>
+</svg>