@heyai-rules/pilo-masterkit 2.1.0 → 3.1.0

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

@@ -1,81 +1,81 @@
----
-name: api-patterns
-description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# API Patterns
-
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
-
-## 🎯 Selective Reading Rule
-
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
-
----
-
-## 📑 Content Map
-
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
-| `response.md` | Envelope pattern, error format, pagination | Response structure |
-| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
-| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
-| `versioning.md` | URI/Header/Query versioning | API evolution planning |
-| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| `rate-limiting.md` | Token bucket, sliding window | API protection |
-| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
-| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
-
----
-
-## 🔗 Related Skills
-
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
-
----
-
-## ✅ Decision Checklist
-
-Before designing an API:
-
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
-
----
-
-## ❌ Anti-Patterns
-
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
-
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
-
----
-
-## Script
-
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
-
+---
+name: api-patterns
+description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# API Patterns
+
+> API design principles and decision-making for 2025.
+> **Learn to THINK, not copy fixed patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+---
+
+## 📑 Content Map
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
+| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
+| `response.md` | Envelope pattern, error format, pagination | Response structure |
+| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
+| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
+| `versioning.md` | URI/Header/Query versioning | API evolution planning |
+| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
+| `rate-limiting.md` | Token bucket, sliding window | API protection |
+| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
+| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+
+---
+
+## 🔗 Related Skills
+
+| Need | Skill |
+|------|-------|
+| API implementation | `@[skills/backend-development]` |
+| Data structure | `@[skills/database-design]` |
+| Security details | `@[skills/security-hardening]` |
+
+---
+
+## ✅ Decision Checklist
+
+Before designing an API:
+
+- [ ] **Asked user about API consumers?**
+- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
+- [ ] **Defined consistent response format?**
+- [ ] **Planned versioning strategy?**
+- [ ] **Considered authentication needs?**
+- [ ] **Planned rate limiting?**
+- [ ] **Documentation approach defined?**
+
+---
+
+## ❌ Anti-Patterns
+
+**DON'T:**
+- Default to REST for everything
+- Use verbs in REST endpoints (/getUsers)
+- Return inconsistent response formats
+- Expose internal errors to clients
+- Skip rate limiting
+
+**DO:**
+- Choose API style based on context
+- Ask about client requirements
+- Document thoroughly
+- Use appropriate status codes
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+

package/.agent/skills/api-patterns/api-style.md

@@ -1,42 +1,42 @@
-# API Style Selection (2025)
-
-> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
-
-## Decision Tree
-
-```
-Who are the API consumers?
-│
-├── Public API / Multiple platforms
-│   └── REST + OpenAPI (widest compatibility)
-│
-├── Complex data needs / Multiple frontends
-│   └── GraphQL (flexible queries)
-│
-├── TypeScript frontend + backend (monorepo)
-│   └── tRPC (end-to-end type safety)
-│
-├── Real-time / Event-driven
-│   └── WebSocket + AsyncAPI
-│
-└── Internal microservices
-    └── gRPC (performance) or REST (simplicity)
-```
-
-## Comparison
-
-| Factor | REST | GraphQL | tRPC |
-|--------|------|---------|------|
-| **Best for** | Public APIs | Complex apps | TS monorepos |
-| **Learning curve** | Low | Medium | Low (if TS) |
-| **Over/under fetching** | Common | Solved | Solved |
-| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
-| **Caching** | HTTP native | Complex | Client-based |
-
-## Selection Questions
-
-1. Who are the API consumers?
-2. Is the frontend TypeScript?
-3. How complex are the data relationships?
-4. Is caching critical?
-5. Public or internal API?
+# API Style Selection (2025)
+
+> REST vs GraphQL vs tRPC - Hangi durumda hangisi?
+
+## Decision Tree
+
+```
+Who are the API consumers?
+│
+├── Public API / Multiple platforms
+│   └── REST + OpenAPI (widest compatibility)
+│
+├── Complex data needs / Multiple frontends
+│   └── GraphQL (flexible queries)
+│
+├── TypeScript frontend + backend (monorepo)
+│   └── tRPC (end-to-end type safety)
+│
+├── Real-time / Event-driven
+│   └── WebSocket + AsyncAPI
+│
+└── Internal microservices
+    └── gRPC (performance) or REST (simplicity)
+```
+
+## Comparison
+
+| Factor | REST | GraphQL | tRPC |
+|--------|------|---------|------|
+| **Best for** | Public APIs | Complex apps | TS monorepos |
+| **Learning curve** | Low | Medium | Low (if TS) |
+| **Over/under fetching** | Common | Solved | Solved |
+| **Type safety** | Manual (OpenAPI) | Schema-based | Automatic |
+| **Caching** | HTTP native | Complex | Client-based |
+
+## Selection Questions
+
+1. Who are the API consumers?
+2. Is the frontend TypeScript?
+3. How complex are the data relationships?
+4. Is caching critical?
+5. Public or internal API?

package/.agent/skills/api-patterns/auth.md

@@ -1,24 +1,24 @@
-# Authentication Patterns
-
-> Choose auth pattern based on use case.
-
-## Selection Guide
-
-| Pattern | Best For |
-|---------|----------|
-| **JWT** | Stateless, microservices |
-| **Session** | Traditional web, simple |
-| **OAuth 2.0** | Third-party integration |
-| **API Keys** | Server-to-server, public APIs |
-| **Passkey** | Modern passwordless (2025+) |
-
-## JWT Principles
-
-```
-Important:
-├── Always verify signature
-├── Check expiration
-├── Include minimal claims
-├── Use short expiry + refresh tokens
-└── Never store sensitive data in JWT
-```
+# Authentication Patterns
+
+> Choose auth pattern based on use case.
+
+## Selection Guide
+
+| Pattern | Best For |
+|---------|----------|
+| **JWT** | Stateless, microservices |
+| **Session** | Traditional web, simple |
+| **OAuth 2.0** | Third-party integration |
+| **API Keys** | Server-to-server, public APIs |
+| **Passkey** | Modern passwordless (2025+) |
+
+## JWT Principles
+
+```
+Important:
+├── Always verify signature
+├── Check expiration
+├── Include minimal claims
+├── Use short expiry + refresh tokens
+└── Never store sensitive data in JWT
+```

package/.agent/skills/api-patterns/documentation.md

@@ -1,26 +1,26 @@
-# API Documentation Principles
-
-> Good docs = happy developers = API adoption.
-
-## OpenAPI/Swagger Essentials
-
-```
-Include:
-├── All endpoints with examples
-├── Request/response schemas
-├── Authentication requirements
-├── Error response formats
-└── Rate limiting info
-```
-
-## Good Documentation Has
-
-```
-Essentials:
-├── Quick start / Getting started
-├── Authentication guide
-├── Complete API reference
-├── Error handling guide
-├── Code examples (multiple languages)
-└── Changelog
-```
+# API Documentation Principles
+
+> Good docs = happy developers = API adoption.
+
+## OpenAPI/Swagger Essentials
+
+```
+Include:
+├── All endpoints with examples
+├── Request/response schemas
+├── Authentication requirements
+├── Error response formats
+└── Rate limiting info
+```
+
+## Good Documentation Has
+
+```
+Essentials:
+├── Quick start / Getting started
+├── Authentication guide
+├── Complete API reference
+├── Error handling guide
+├── Code examples (multiple languages)
+└── Changelog
+```

package/.agent/skills/api-patterns/graphql.md

@@ -1,41 +1,41 @@
-# GraphQL Principles
-
-> Flexible queries for complex, interconnected data.
-
-## When to Use
-
-```
-✅ Good fit:
-├── Complex, interconnected data
-├── Multiple frontend platforms
-├── Clients need flexible queries
-├── Evolving data requirements
-└── Reducing over-fetching matters
-
-❌ Poor fit:
-├── Simple CRUD operations
-├── File upload heavy
-├── HTTP caching important
-└── Team unfamiliar with GraphQL
-```
-
-## Schema Design Principles
-
-```
-Principles:
-├── Think in graphs, not endpoints
-├── Design for evolvability (no versions)
-├── Use connections for pagination
-├── Be specific with types (not generic "data")
-└── Handle nullability thoughtfully
-```
-
-## Security Considerations
-
-```
-Protect against:
-├── Query depth attacks → Set max depth
-├── Query complexity → Calculate cost
-├── Batching abuse → Limit batch size
-├── Introspection → Disable in production
-```
+# GraphQL Principles
+
+> Flexible queries for complex, interconnected data.
+
+## When to Use
+
+```
+✅ Good fit:
+├── Complex, interconnected data
+├── Multiple frontend platforms
+├── Clients need flexible queries
+├── Evolving data requirements
+└── Reducing over-fetching matters
+
+❌ Poor fit:
+├── Simple CRUD operations
+├── File upload heavy
+├── HTTP caching important
+└── Team unfamiliar with GraphQL
+```
+
+## Schema Design Principles
+
+```
+Principles:
+├── Think in graphs, not endpoints
+├── Design for evolvability (no versions)
+├── Use connections for pagination
+├── Be specific with types (not generic "data")
+└── Handle nullability thoughtfully
+```
+
+## Security Considerations
+
+```
+Protect against:
+├── Query depth attacks → Set max depth
+├── Query complexity → Calculate cost
+├── Batching abuse → Limit batch size
+├── Introspection → Disable in production
+```

package/.agent/skills/api-patterns/rate-limiting.md

@@ -1,31 +1,31 @@
-# Rate Limiting Principles
-
-> Protect your API from abuse and overload.
-
-## Why Rate Limit
-
-```
-Protect against:
-├── Brute force attacks
-├── Resource exhaustion
-├── Cost overruns (if pay-per-use)
-└── Unfair usage
-```
-
-## Strategy Selection
-
-| Type | How | When |
-|------|-----|------|
-| **Token bucket** | Burst allowed, refills over time | Most APIs |
-| **Sliding window** | Smooth distribution | Strict limits |
-| **Fixed window** | Simple counters per window | Basic needs |
-
-## Response Headers
-
-```
-Include in headers:
-├── X-RateLimit-Limit (max requests)
-├── X-RateLimit-Remaining (requests left)
-├── X-RateLimit-Reset (when limit resets)
-└── Return 429 when exceeded
-```
+# Rate Limiting Principles
+
+> Protect your API from abuse and overload.
+
+## Why Rate Limit
+
+```
+Protect against:
+├── Brute force attacks
+├── Resource exhaustion
+├── Cost overruns (if pay-per-use)
+└── Unfair usage
+```
+
+## Strategy Selection
+
+| Type | How | When |
+|------|-----|------|
+| **Token bucket** | Burst allowed, refills over time | Most APIs |
+| **Sliding window** | Smooth distribution | Strict limits |
+| **Fixed window** | Simple counters per window | Basic needs |
+
+## Response Headers
+
+```
+Include in headers:
+├── X-RateLimit-Limit (max requests)
+├── X-RateLimit-Remaining (requests left)
+├── X-RateLimit-Reset (when limit resets)
+└── Return 429 when exceeded
+```

package/.agent/skills/api-patterns/response.md

@@ -1,37 +1,37 @@
-# Response Format Principles
-
-> Consistency is key - choose a format and stick to it.
-
-## Common Patterns
-
-```
-Choose one:
-├── Envelope pattern ({ success, data, error })
-├── Direct data (just return the resource)
-└── HAL/JSON:API (hypermedia)
-```
-
-## Error Response
-
-```
-Include:
-├── Error code (for programmatic handling)
-├── User message (for display)
-├── Details (for debugging, field-level errors)
-├── Request ID (for support)
-└── NOT internal details (security!)
-```
-
-## Pagination Types
-
-| Type | Best For | Trade-offs |
-|------|----------|------------|
-| **Offset** | Simple, jumpable | Performance on large datasets |
-| **Cursor** | Large datasets | Can't jump to page |
-| **Keyset** | Performance critical | Requires sortable key |
-
-### Selection Questions
-
-1. How large is the dataset?
-2. Do users need to jump to specific pages?
-3. Is data frequently changing?
+# Response Format Principles
+
+> Consistency is key - choose a format and stick to it.
+
+## Common Patterns
+
+```
+Choose one:
+├── Envelope pattern ({ success, data, error })
+├── Direct data (just return the resource)
+└── HAL/JSON:API (hypermedia)
+```
+
+## Error Response
+
+```
+Include:
+├── Error code (for programmatic handling)
+├── User message (for display)
+├── Details (for debugging, field-level errors)
+├── Request ID (for support)
+└── NOT internal details (security!)
+```
+
+## Pagination Types
+
+| Type | Best For | Trade-offs |
+|------|----------|------------|
+| **Offset** | Simple, jumpable | Performance on large datasets |
+| **Cursor** | Large datasets | Can't jump to page |
+| **Keyset** | Performance critical | Requires sortable key |
+
+### Selection Questions
+
+1. How large is the dataset?
+2. Do users need to jump to specific pages?
+3. Is data frequently changing?

package/.agent/skills/api-patterns/rest.md

@@ -1,40 +1,40 @@
-# REST Principles
-
-> Resource-based API design - nouns not verbs.
-
-## Resource Naming Rules
-
-```
-Principles:
-├── Use NOUNS, not verbs (resources, not actions)
-├── Use PLURAL forms (/users not /user)
-├── Use lowercase with hyphens (/user-profiles)
-├── Nest for relationships (/users/123/posts)
-└── Keep shallow (max 3 levels deep)
-```
-
-## HTTP Method Selection
-
-| Method | Purpose | Idempotent? | Body? |
-|--------|---------|-------------|-------|
-| **GET** | Read resource(s) | Yes | No |
-| **POST** | Create new resource | No | Yes |
-| **PUT** | Replace entire resource | Yes | Yes |
-| **PATCH** | Partial update | No | Yes |
-| **DELETE** | Remove resource | Yes | No |
-
-## Status Code Selection
-
-| Situation | Code | Why |
-|-----------|------|-----|
-| Success (read) | 200 | Standard success |
-| Created | 201 | New resource created |
-| No content | 204 | Success, nothing to return |
-| Bad request | 400 | Malformed request |
-| Unauthorized | 401 | Missing/invalid auth |
-| Forbidden | 403 | Valid auth, no permission |
-| Not found | 404 | Resource doesn't exist |
-| Conflict | 409 | State conflict (duplicate) |
-| Validation error | 422 | Valid syntax, invalid data |
-| Rate limited | 429 | Too many requests |
-| Server error | 500 | Our fault |
+# REST Principles
+
+> Resource-based API design - nouns not verbs.
+
+## Resource Naming Rules
+
+```
+Principles:
+├── Use NOUNS, not verbs (resources, not actions)
+├── Use PLURAL forms (/users not /user)
+├── Use lowercase with hyphens (/user-profiles)
+├── Nest for relationships (/users/123/posts)
+└── Keep shallow (max 3 levels deep)
+```
+
+## HTTP Method Selection
+
+| Method | Purpose | Idempotent? | Body? |
+|--------|---------|-------------|-------|
+| **GET** | Read resource(s) | Yes | No |
+| **POST** | Create new resource | No | Yes |
+| **PUT** | Replace entire resource | Yes | Yes |
+| **PATCH** | Partial update | No | Yes |
+| **DELETE** | Remove resource | Yes | No |
+
+## Status Code Selection
+
+| Situation | Code | Why |
+|-----------|------|-----|
+| Success (read) | 200 | Standard success |
+| Created | 201 | New resource created |
+| No content | 204 | Success, nothing to return |
+| Bad request | 400 | Malformed request |
+| Unauthorized | 401 | Missing/invalid auth |
+| Forbidden | 403 | Valid auth, no permission |
+| Not found | 404 | Resource doesn't exist |
+| Conflict | 409 | State conflict (duplicate) |
+| Validation error | 422 | Valid syntax, invalid data |
+| Rate limited | 429 | Too many requests |
+| Server error | 500 | Our fault |