locus-product-planning 1.1.0 → 1.2.0

package/.claude-plugin/marketplace.json

@@ -3,8 +3,8 @@
   "name": "locus",
   "display_name": "Locus - Project Planning",
   "description": "Your center point for planning and building projects with AI. Go from idea to implementation through 4 simple steps: Vision -> Features -> Design -> Build.",
-  "long_description": "Locus provides a comprehensive skills framework for AI-powered project planning. It includes:\n\n- 40+ specialized skills covering executive strategy, product management, engineering leadership, and developer specializations\n- 14 agent definitions for specialized perspectives\n- Automatic skill loading and discovery\n- Simple 4-step project planning workflow\n\nPerfect for:\n- Starting new projects from scratch\n- Getting diverse perspectives on technical decisions\n- Following proven development workflows\n- Organizing complex multi-step implementations",
-  "version": "1.1.0",
+  "long_description": "Locus provides a comprehensive skills framework for AI-powered project planning. It includes:\n\n- 46 specialized skills covering executive strategy, product management, engineering leadership, and developer specializations\n- 14 agent definitions for specialized perspectives\n- Automatic skill loading and discovery\n- Simple 4-step project planning workflow\n\nPerfect for:\n- Starting new projects from scratch\n- Getting diverse perspectives on technical decisions\n- Following proven development workflows\n- Organizing complex multi-step implementations",
+  "version": "1.2.0",
   "author": "swiggityswerve",
   "license": "MIT",
   "repository": "https://github.com/SwiggitySwerve/locus-product-planning",

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://claude.ai/plugin.json",
   "name": "locus",
-  "version": "1.1.0",
-  "description": "AI-powered project planning with 40+ skills: Vision -> Features -> Design -> Build",
+  "version": "1.2.0",
+  "description": "AI-powered project planning with 46 skills: Vision -> Features -> Design -> Build",
   "author": "swiggityswerve",
   "license": "MIT",
   "homepage": "https://github.com/SwiggitySwerve/locus-product-planning",

package/README.md

@@ -2,7 +2,7 @@
 
 **Your center point for planning and building products with AI.**
 
-Locus guides you from idea to implementation through a simple 4-step process, backed by 40+ specialized skills and 14 agent definitions.
+Locus guides you from idea to implementation through a simple 4-step process, backed by 46 specialized skills and 14 agent definitions.
 
 ## Quick Start
 
@@ -85,7 +85,7 @@ Or just describe what you want: "I want to build..."
 | `find_skills` | List skills with optional category/tier/search filters |
 | `find_agents` | List available agent definitions |
 
-## Skills Library (40+)
+## Skills Library (46)
 
 ### Executive Suite
 Strategic leadership perspectives:
@@ -115,18 +115,21 @@ Technical leadership and architecture:
 ### Developer Specializations
 Domain expertise organized by category:
 
-**Core**: `frontend-developer`, `backend-developer`, `fullstack-developer`, `mobile-developer`
+**Core**: `frontend-developer`, `backend-developer`, `fullstack-developer`, `mobile-developer`, `api-designer`
 
 **Languages**: `typescript-pro`, `python-pro`, `rust-engineer`, `golang-pro`, `java-architect`
 
-**Infrastructure**: `devops-engineer`, `cloud-architect`, `kubernetes-specialist`, `platform-engineer`, `security-engineer`, `sre-engineer`
+**Infrastructure**: `devops-engineer`, `cloud-architect`, `kubernetes-specialist`, `platform-engineer`, `security-engineer`, `sre-engineer`, `database-architect`
 
 **Data & AI**: `data-engineer`, `data-scientist`, `ml-engineer`, `llm-architect`
 
-**Quality**: `qa-expert`, `performance-engineer`, `security-auditor`, `accessibility-tester`
+**Quality**: `qa-expert`, `performance-engineer`, `security-auditor`, `accessibility-tester`, `test-automation-engineer`
+
+**Design**: `ui-ux-designer`
 
 ### Specialists
 - `locus:compliance-specialist` - Regulatory compliance
+- `locus:technical-writer` - Documentation and technical writing
 
 ## Agents (14)
 
@@ -141,13 +144,14 @@ Pre-configured agent definitions for specialized perspectives:
 ## Project Structure
 
 ```
-skills/                  # 40+ skill definitions
+skills/                  # 46 skill definitions
 ├── using-locus/         # Main bootstrap skill
 ├── 01-executive-suite/  # C-suite perspectives
 ├── 02-product-management/
 ├── 03-engineering-leadership/
 ├── 04-developer-specializations/
 │   ├── core/
+│   ├── design/
 │   ├── languages/
 │   ├── infrastructure/
 │   ├── data-ai/
@@ -175,7 +179,7 @@ opencode.json            # OpenCode commands
 git clone https://github.com/SwiggitySwerve/locus-product-planning.git
 cd locus-product-planning
 npm install
-npm test        # 161 tests
+npm test        # 184 tests
 npm run build   # Compile TypeScript
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "locus-product-planning",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "AI-powered product planning for OpenCode - Vision → Features → Design → Build",
   "type": "module",
   "main": "dist/index.js",

package/skills/04-developer-specializations/core/api-designer/SKILL.md

@@ -0,0 +1,579 @@
+---
+name: api-designer
+description: REST and GraphQL API design, versioning strategies, documentation, and building developer-friendly interfaces
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: core
+  council: code-review-council
+---
+
+# API Designer
+
+You embody the perspective of a senior API designer with expertise in creating intuitive, well-documented, and developer-friendly APIs that stand the test of time.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing new APIs (REST, GraphQL, gRPC)
+- Reviewing API designs for consistency
+- Planning API versioning strategies
+- Writing API documentation
+- Designing error handling and response formats
+- Creating API security patterns
+- Building SDK-friendly interfaces
+- Planning backwards-compatible changes
+
+## Core Competencies
+
+### 1. API Design
+- Resource modeling and naming
+- HTTP method semantics
+- Response format consistency
+- Error handling patterns
+
+### 2. Documentation
+- OpenAPI/Swagger specifications
+- Interactive documentation
+- Code examples and SDKs
+- Changelog management
+
+### 3. Versioning
+- Breaking vs non-breaking changes
+- Deprecation strategies
+- Migration support
+- Multiple version maintenance
+
+### 4. Security
+- Authentication patterns
+- Authorization design
+- Rate limiting
+- Input validation
+
+## REST API Design
+
+### Resource Naming Conventions
+
+| Pattern | Example | Description |
+|---------|---------|-------------|
+| **Collection** | `/users` | List of resources |
+| **Instance** | `/users/123` | Single resource |
+| **Sub-resource** | `/users/123/orders` | Related collection |
+| **Action** | `/users/123/activate` | Non-CRUD operation |
+
+### Naming Rules
+- Use nouns, not verbs (except actions)
+- Use plural for collections
+- Use kebab-case for multi-word
+- Avoid deep nesting (max 2-3 levels)
+
+```
+Good:
+  GET  /users
+  GET  /users/123
+  GET  /users/123/orders
+  POST /users/123/reset-password
+
+Bad:
+  GET  /getUsers
+  GET  /user/123  (inconsistent plural)
+  GET  /users/123/orders/456/items/789/details (too deep)
+```
+
+### HTTP Methods
+
+| Method | Use | Idempotent | Safe |
+|--------|-----|------------|------|
+| **GET** | Read resource(s) | Yes | Yes |
+| **POST** | Create resource | No | No |
+| **PUT** | Replace resource | Yes | No |
+| **PATCH** | Partial update | No* | No |
+| **DELETE** | Remove resource | Yes | No |
+
+*PATCH can be idempotent with proper design
+
+### Status Codes
+
+| Range | Meaning | Common Codes |
+|-------|---------|--------------|
+| **2xx** | Success | 200 OK, 201 Created, 204 No Content |
+| **3xx** | Redirect | 301 Moved, 304 Not Modified |
+| **4xx** | Client error | 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 409 Conflict, 422 Unprocessable |
+| **5xx** | Server error | 500 Internal Error, 502 Bad Gateway, 503 Unavailable |
+
+### Status Code Decision Tree
+
+```
+Success?
+├─ Yes → Resource returned?
+│        ├─ Yes → 200 OK
+│        └─ No  → Created?
+│                 ├─ Yes → 201 Created
+│                 └─ No  → 204 No Content
+│
+└─ No → Client's fault?
+        ├─ Yes → Auth issue?
+        │        ├─ Yes → Needs login? → 401 Unauthorized
+        │        │        └─ Has access? → 403 Forbidden
+        │        └─ No  → Resource exists?
+        │                 ├─ No  → 404 Not Found
+        │                 └─ Yes → Valid input?
+        │                          ├─ No  → 400 Bad Request (syntax)
+        │                          │        422 Unprocessable (semantic)
+        │                          └─ Yes → 409 Conflict (state)
+        │
+        └─ No (Server's fault) → 500/502/503
+```
+
+## Response Format
+
+### Standard Response Structure
+
+```json
+// Success response
+{
+  "data": {
+    "id": "user_123",
+    "type": "user",
+    "attributes": {
+      "email": "user@example.com",
+      "name": "John Doe",
+      "created_at": "2024-01-15T10:30:00Z"
+    },
+    "relationships": {
+      "organization": {
+        "id": "org_456",
+        "type": "organization"
+      }
+    }
+  },
+  "meta": {
+    "request_id": "req_abc123"
+  }
+}
+
+// Collection response
+{
+  "data": [...],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "per_page": 20,
+    "request_id": "req_abc123"
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "last": "/users?page=5"
+  }
+}
+```
+
+### Error Response Structure
+
+```json
+{
+  "error": {
+    "code": "validation_error",
+    "message": "The request contains invalid parameters",
+    "details": [
+      {
+        "field": "email",
+        "code": "invalid_format",
+        "message": "Must be a valid email address"
+      },
+      {
+        "field": "age",
+        "code": "out_of_range",
+        "message": "Must be between 18 and 120"
+      }
+    ],
+    "request_id": "req_abc123",
+    "documentation_url": "https://api.example.com/docs/errors#validation_error"
+  }
+}
+```
+
+### Error Code Taxonomy
+
+```
+authentication_error    - Auth token invalid/expired
+authorization_error     - User lacks permission
+validation_error        - Input validation failed
+not_found              - Resource doesn't exist
+conflict               - Resource state conflict
+rate_limit_exceeded    - Too many requests
+internal_error         - Server error (hide details)
+service_unavailable    - Temporary outage
+```
+
+## Pagination
+
+### Cursor-Based (Recommended)
+
+```
+GET /orders?cursor=eyJpZCI6MTIzfQ&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "has_more": true,
+    "next_cursor": "eyJpZCI6MTQzfQ"
+  }
+}
+```
+
+**Pros**: Stable with concurrent writes, no offset performance issues
+**Cons**: Can't jump to arbitrary page
+
+### Offset-Based
+
+```
+GET /orders?offset=40&limit=20
+
+Response:
+{
+  "data": [...],
+  "pagination": {
+    "total": 500,
+    "offset": 40,
+    "limit": 20
+  }
+}
+```
+
+**Pros**: Simple, supports page jumping
+**Cons**: Unstable with writes, slow for large offsets
+
+## Filtering and Sorting
+
+### Filter Patterns
+
+```
+# Simple equality
+GET /users?status=active
+
+# Multiple values
+GET /users?status=active,pending
+
+# Comparison operators
+GET /orders?total[gte]=100&total[lte]=500
+
+# Date ranges
+GET /events?created_at[gte]=2024-01-01&created_at[lt]=2024-02-01
+
+# Search
+GET /products?q=laptop
+
+# Nested filters (if needed)
+GET /users?organization.plan=enterprise
+```
+
+### Sorting
+
+```
+# Single field
+GET /users?sort=created_at
+
+# Descending
+GET /users?sort=-created_at
+
+# Multiple fields
+GET /users?sort=-created_at,name
+```
+
+## Versioning Strategies
+
+### URL Path Versioning (Recommended)
+
+```
+GET /v1/users
+GET /v2/users
+```
+
+**Pros**: Explicit, easy to route, cache-friendly
+**Cons**: Not "pure" REST
+
+### Header Versioning
+
+```
+GET /users
+Accept: application/vnd.api+json; version=2
+```
+
+**Pros**: Clean URLs
+**Cons**: Hidden, harder to test, cache complexity
+
+### Version Lifecycle
+
+```
+v1 (deprecated) ─────────> sunset date ───────> removed
+v2 (current)    ─────────> stable ────────────> deprecated (when v3)
+v3 (preview)    ─────────> stable (becomes current)
+```
+
+### Breaking vs Non-Breaking Changes
+
+| Non-Breaking (Safe) | Breaking (Requires New Version) |
+|---------------------|----------------------------------|
+| Add optional field | Remove field |
+| Add new endpoint | Change field type |
+| Add optional parameter | Change field meaning |
+| Expand enum values | Remove enum value |
+| Relax validation | Tighten validation |
+| Add HTTP method | Change URL structure |
+
+## GraphQL Design
+
+### Schema Design
+
+```graphql
+type User {
+  id: ID!
+  email: String!
+  name: String!
+  createdAt: DateTime!
+  
+  # Relationships with pagination
+  orders(first: Int, after: String): OrderConnection!
+  
+  # Computed fields
+  totalSpent: Money!
+}
+
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int!
+}
+
+type OrderEdge {
+  cursor: String!
+  node: Order!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+### Query Patterns
+
+```graphql
+# Good: Specific fields, connection pattern
+query GetUserOrders($userId: ID!, $first: Int!, $after: String) {
+  user(id: $userId) {
+    id
+    name
+    orders(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          total
+          status
+        }
+      }
+      pageInfo {
+        hasNextPage
+        endCursor
+      }
+    }
+  }
+}
+
+# Avoid: Deeply nested queries without limits
+query Bad {
+  users {
+    orders {
+      items {
+        product {
+          reviews {
+            # This can explode
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Mutation Patterns
+
+```graphql
+# Input types for mutations
+input CreateUserInput {
+  email: String!
+  name: String!
+  organizationId: ID
+}
+
+# Consistent mutation response
+type CreateUserPayload {
+  user: User
+  errors: [UserError!]!
+}
+
+type UserError {
+  field: String
+  message: String!
+  code: ErrorCode!
+}
+
+mutation CreateUser($input: CreateUserInput!) {
+  createUser(input: $input) {
+    user {
+      id
+      email
+    }
+    errors {
+      field
+      message
+    }
+  }
+}
+```
+
+## API Security
+
+### Authentication
+
+| Method | Use Case |
+|--------|----------|
+| **API Keys** | Server-to-server, simple auth |
+| **OAuth 2.0 + OIDC** | User authorization, SSO |
+| **JWT** | Stateless session tokens |
+| **mTLS** | High-security B2B |
+
+### Authorization Header
+
+```
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+### Rate Limiting Headers
+
+```
+X-RateLimit-Limit: 1000
+X-RateLimit-Remaining: 998
+X-RateLimit-Reset: 1640995200
+Retry-After: 60  (when limited)
+```
+
+### Input Validation Checklist
+
+- [ ] Validate content-type header
+- [ ] Limit request body size
+- [ ] Validate all input parameters
+- [ ] Sanitize strings for injection
+- [ ] Validate file uploads (type, size)
+- [ ] Prevent mass assignment
+
+## Documentation
+
+### OpenAPI Specification Structure
+
+```yaml
+openapi: 3.1.0
+info:
+  title: My API
+  version: 1.0.0
+  description: |
+    # Introduction
+    Welcome to the API documentation.
+    
+    ## Authentication
+    All requests require an API key...
+
+servers:
+  - url: https://api.example.com/v1
+    description: Production
+
+paths:
+  /users:
+    get:
+      summary: List users
+      operationId: listUsers
+      tags: [Users]
+      parameters:
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [active, inactive]
+      responses:
+        '200':
+          description: List of users
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UserList'
+              examples:
+                default:
+                  $ref: '#/components/examples/UserListExample'
+```
+
+### Documentation Requirements
+
+- [ ] All endpoints documented
+- [ ] Request/response examples
+- [ ] Error responses documented
+- [ ] Authentication explained
+- [ ] Rate limits documented
+- [ ] Changelog maintained
+- [ ] Interactive playground
+
+## API Design Checklist
+
+### Before Building
+
+- [ ] Resources and relationships identified
+- [ ] URL structure consistent
+- [ ] HTTP methods appropriate
+- [ ] Response format standardized
+- [ ] Error format defined
+- [ ] Versioning strategy chosen
+- [ ] Authentication mechanism selected
+- [ ] Rate limiting planned
+
+### Before Releasing
+
+- [ ] OpenAPI spec complete
+- [ ] All endpoints tested
+- [ ] Error handling consistent
+- [ ] Security review complete
+- [ ] Performance benchmarked
+- [ ] Monitoring in place
+- [ ] Deprecation policy documented
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Better Approach |
+|--------------|-----------------|
+| Verbs in URLs | Use HTTP methods semantically |
+| Inconsistent naming | Establish conventions early |
+| Missing pagination | Always paginate collections |
+| Generic 500 errors | Proper status codes and messages |
+| No request IDs | Include for debugging |
+| Undocumented changes | Maintain changelog |
+| Breaking changes silently | Version and communicate |
+
+## Constraints
+
+- Always use HTTPS
+- Include request ID in all responses
+- Document all public endpoints
+- Version from day one
+- Never expose internal errors
+- Rate limit all endpoints
+- Validate all input
+
+## Related Skills
+
+- `backend-developer` - Implementation
+- `frontend-developer` - Consumer perspective
+- `security-engineer` - API security
+- `technical-writer` - Documentation