@softspark/ai-toolkit 1.0.0

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

@@ -0,0 +1,305 @@
+---
+name: api-patterns
+description: "Loaded when user asks about REST API design or GraphQL patterns"
+effort: medium
+user-invocable: false
+---
+
+# API Patterns Skill
+
+## REST API Design
+
+### Resource Naming
+
+```
+# Collection
+GET    /api/v1/documents        # List documents
+POST   /api/v1/documents        # Create document
+
+# Single resource
+GET    /api/v1/documents/{id}   # Get document
+PUT    /api/v1/documents/{id}   # Replace document
+PATCH  /api/v1/documents/{id}   # Update document
+DELETE /api/v1/documents/{id}   # Delete document
+
+# Nested resources
+GET    /api/v1/users/{id}/documents  # User's documents
+```
+
+### HTTP Status Codes
+
+| Code | Meaning | When to Use |
+|------|---------|-------------|
+| 200 | OK | Successful GET/PUT/PATCH |
+| 201 | Created | Successful POST |
+| 204 | No Content | Successful DELETE |
+| 400 | Bad Request | Invalid input |
+| 401 | Unauthorized | Missing/invalid auth |
+| 403 | Forbidden | No permission |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Duplicate resource |
+| 422 | Unprocessable | Validation error |
+| 429 | Too Many Requests | Rate limited |
+| 500 | Internal Error | Server error |
+
+### Response Format
+
+```json
+{
+  "data": {
+    "id": "123",
+    "type": "document",
+    "attributes": {
+      "title": "Example",
+      "content": "..."
+    }
+  },
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "per_page": 10
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": [
+      {"field": "title", "message": "Title is required"},
+      {"field": "limit", "message": "Must be between 1 and 100"}
+    ]
+  }
+}
+```
+
+---
+
+## FastAPI Implementation
+
+```python
+from fastapi import FastAPI, HTTPException, Query, Path
+from pydantic import BaseModel, Field
+
+app = FastAPI(title="RAG-MCP API", version="1.0.0")
+
+class SearchRequest(BaseModel):
+    query: str = Field(..., min_length=1, description="Search query")
+    limit: int = Field(10, ge=1, le=100, description="Max results")
+
+class SearchResult(BaseModel):
+    id: str
+    title: str
+    score: float
+    content: str
+
+class SearchResponse(BaseModel):
+    results: list[SearchResult]
+    total: int
+
+@app.post("/api/v1/search", response_model=SearchResponse)
+async def search(request: SearchRequest):
+    """Search the knowledge base.
+
+    Args:
+        request: Search parameters
+
+    Returns:
+        Search results with scores
+    """
+    try:
+        results = await perform_search(request.query, request.limit)
+        return SearchResponse(results=results, total=len(results))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+```
+
+---
+
+## JSON-RPC 2.0 (MCP Pattern)
+
+### Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "search",
+    "arguments": {"query": "test"}
+  }
+}
+```
+
+### Success Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "content": [
+      {"type": "text", "text": "Results..."}
+    ]
+  }
+}
+```
+
+### Error Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Invalid params",
+    "data": {"field": "query", "message": "Required"}
+  }
+}
+```
+
+---
+
+## Pagination
+
+### Offset-based
+
+```
+GET /api/v1/documents?page=2&per_page=20
+```
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "total": 150,
+    "page": 2,
+    "per_page": 20,
+    "total_pages": 8
+  }
+}
+```
+
+### Cursor-based (Recommended for Large Datasets)
+
+```
+GET /api/v1/documents?cursor=abc123&limit=20
+```
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "next_cursor": "xyz789",
+    "has_more": true
+  }
+}
+```
+
+---
+
+## Rate Limiting
+
+### Headers
+
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1699999999
+```
+
+### Implementation
+
+```python
+from fastapi import Request
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+
+@app.get("/api/v1/search")
+@limiter.limit("100/minute")
+async def search(request: Request, query: str):
+    ...
+```
+
+---
+
+## Authentication
+
+### API Key (Simple)
+
+```python
+from fastapi import Depends, HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+api_key_header = APIKeyHeader(name="X-API-Key")
+
+async def verify_api_key(api_key: str = Security(api_key_header)):
+    if api_key != settings.API_KEY:
+        raise HTTPException(status_code=401, detail="Invalid API key")
+    return api_key
+
+@app.get("/api/v1/protected")
+async def protected_endpoint(api_key: str = Depends(verify_api_key)):
+    ...
+```
+
+### JWT (Production)
+
+```python
+from fastapi import Depends
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+import jwt
+
+security = HTTPBearer()
+
+async def verify_jwt(credentials: HTTPAuthorizationCredentials = Depends(security)):
+    try:
+        payload = jwt.decode(
+            credentials.credentials,
+            settings.JWT_SECRET,
+            algorithms=["HS256"]
+        )
+        return payload
+    except jwt.InvalidTokenError:
+        raise HTTPException(status_code=401, detail="Invalid token")
+```
+
+---
+
+## Versioning
+
+### URL Path (Recommended)
+
+```
+/api/v1/documents
+/api/v2/documents
+```
+
+### Header
+
+```
+Accept: application/vnd.myapi.v1+json
+```
+
+---
+
+## Best Practices
+
+- [ ] Use HTTPS only
+- [ ] Version your API
+- [ ] Validate all inputs
+- [ ] Use proper HTTP methods and status codes
+- [ ] Implement rate limiting
+- [ ] Include pagination for lists
+- [ ] Return consistent error format
+- [ ] Document with OpenAPI/Swagger
+- [ ] Log requests for debugging
+- [ ] Set reasonable timeouts

package/app/skills/app-builder/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: app-builder
+description: "Loaded when user asks to scaffold or build a full-stack app"
+effort: medium
+user-invocable: false
+---
+
+# App Builder Skill
+
+## Project Type Detection
+
+| Keywords | Project Type | Primary Agents |
+|----------|--------------|----------------|
+| landing, website, marketing | Static Site | frontend-specialist |
+| dashboard, admin, crud | Web App | frontend + backend |
+| api, rest, graphql | API Only | backend-specialist |
+| mobile, ios, android | Mobile App | mobile-developer |
+| cli, command, terminal | CLI Tool | backend-specialist |
+| game, unity, godot | Game | game-developer |
+| ai, ml, rag | AI/ML | rag-engineer |
+| e-commerce, shop, store | E-commerce | backend + frontend |
+
+---
+
+## Tech Stack Selection (2025)
+
+### Web Applications
+
+| Scenario | Stack |
+|----------|-------|
+| Full-stack, SSR | Next.js 14+ (App Router) |
+| SPA with API | React + Vite |
+| Vue ecosystem | Nuxt 3 |
+| Static/Blog | Astro |
+| E-commerce | Next.js + Medusa/Shopify |
+
+### Mobile Applications
+
+| Scenario | Stack |
+|----------|-------|
+| Cross-platform (JS team) | React Native + Expo |
+| Cross-platform (any) | Flutter |
+| iOS only | SwiftUI |
+| Android only | Kotlin + Jetpack Compose |
+
+### Backend/API
+
+| Scenario | Stack |
+|----------|-------|
+| Node.js, edge-ready | Hono |
+| Node.js, high perf | Fastify |
+| Python, async | FastAPI |
+| PHP, full-featured | Laravel |
+| E-commerce | Magento/Sylius/PrestaShop |
+
+### Database
+
+| Scenario | Stack |
+|----------|-------|
+| General purpose | PostgreSQL |
+| Serverless | Neon (PG), Turso (SQLite) |
+| Document store | MongoDB |
+| Vector search | PostgreSQL + pgvector |
+| Cache | Redis / Upstash |
+
+---
+
+## Project Templates
+
+### Next.js Full-Stack
+
+```
+project/
+├── src/
+│   ├── app/              # App Router
+│   │   ├── (auth)/       # Auth group
+│   │   ├── api/          # API routes
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/       # Shared components
+│   │   └── ui/           # UI primitives
+│   ├── lib/              # Utilities
+│   └── server/           # Server-only code
+├── prisma/               # Database schema
+├── public/
+├── next.config.ts
+├── tailwind.config.ts
+└── package.json
+```
+
+### FastAPI Backend
+
+```
+project/
+├── app/
+│   ├── api/
+│   │   └── v1/
+│   │       └── endpoints/
+│   ├── core/             # Config, security
+│   ├── models/           # Pydantic models
+│   ├── db/               # Database
+│   └── main.py
+├── tests/
+├── alembic/              # Migrations
+├── pyproject.toml
+└── Dockerfile
+```
+
+### React Native + Expo
+
+```
+project/
+├── app/                  # Expo Router
+│   ├── (tabs)/
+│   ├── _layout.tsx
+│   └── index.tsx
+├── components/
+├── hooks/
+├── store/                # State management
+├── services/             # API clients
+├── app.json
+└── package.json
+```
+
+---
+
+## Agent Coordination
+
+### New Project Flow
+
+```
+1. project-planner     → Task breakdown
+2. database-architect  → Schema design
+3. backend-specialist  → API implementation
+4. frontend-specialist → UI implementation
+5. test-engineer       → Test coverage
+6. devops-implementer  → Deployment
+```
+
+### Feature Addition Flow
+
+```
+1. explorer-agent      → Understand codebase
+2. project-planner     → Plan changes
+3. [appropriate agent] → Implement
+4. test-engineer       → Add tests
+5. code-reviewer       → Review
+```
+
+---
+
+## Common Patterns
+
+### Authentication
+- JWT for APIs
+- Session for web apps
+- OAuth for third-party
+
+### State Management
+- Server state: TanStack Query
+- Client state: Zustand/Jotai
+- Form state: React Hook Form
+
+### Styling
+- Tailwind CSS as default
+- CSS Modules for isolation
+- Styled Components for dynamic
+
+### Testing
+- Unit: Jest/Vitest
+- E2E: Playwright
+- API: Supertest
+
+---
+
+## Best Practices
+
+- ✅ Start with TypeScript
+- ✅ Add linting (ESLint/Biome)
+- ✅ Use environment variables
+- ✅ Set up CI/CD from start
+- ✅ Document as you build
+
+- ❌ Don't skip tests
+- ❌ Don't hardcode config
+- ❌ Don't ignore accessibility
+- ❌ Don't over-engineer early

package/app/skills/architecture-audit/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: architecture-audit
+description: "Explore codebase organically for architectural friction, discover shallow modules, and propose module-deepening refactors as GitHub issue RFCs using parallel sub-agent interface designs. Use when user wants to improve architecture, find shallow modules, deepen modules, or reduce coupling."
+user-invocable: true
+effort: high
+argument-hint: "[area to audit or 'full codebase']"
+allowed-tools: Read, Grep, Glob, Bash, Agent
+---
+
+# Architecture Audit
+
+$ARGUMENTS
+
+Explore a codebase organically, surface architectural friction, and propose module-deepening refactors as GitHub issue RFCs.
+
+## Usage
+
+```
+/architecture-audit [area to audit or 'full codebase']
+```
+
+## What This Command Does
+
+1. **Explores** codebase organically — friction IS the signal
+2. **Presents** deepening candidates to user
+3. **Frames** problem space for chosen candidate
+4. **Spawns** 3+ parallel sub-agents for radically different interface designs
+5. **Compares** and recommends
+6. **Files** RFC as GitHub issue
+
+## Key Concept
+
+A **deep module** (Ousterhout) has a small interface hiding a large implementation. Deep modules enhance testability, AI navigation, and enable boundary testing.
+
+A **shallow module** has a large interface with thin implementation — avoid.
+
+## Process
+
+### 1. Organic Exploration
+
+Use Agent (subagent_type=Explore) to navigate the codebase naturally. Note friction:
+
+- Where does understanding one concept require bouncing between many small files?
+- Where are modules so shallow the interface is nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability but real bugs hide in how they're called?
+- Where do tightly-coupled modules create integration risk in the seams?
+- What is untested or hard to test?
+
+### 2. Present Candidates
+
+Numbered list. For each candidate show:
+
+| Field | Content |
+|-------|---------|
+| Cluster | Which modules/concepts are involved |
+| Why coupled | Shared types, call patterns, co-ownership |
+| Dependency category | In-process, Local-substitutable, Ports & Adapters, or True external (see reference/) |
+| Test impact | What existing tests would be replaced by boundary tests |
+
+Do NOT propose interfaces yet. Ask: "Which would you like to explore?"
+
+### 3. Frame the Problem Space
+
+For the chosen candidate, write a user-facing explanation:
+- Constraints any new interface would satisfy
+- Dependencies it would rely on
+- Rough illustrative code sketch (not a proposal — just grounding)
+
+Show to user, then immediately proceed to step 4.
+
+### 4. Design Multiple Interfaces
+
+Spawn 3+ sub-agents in parallel via Agent tool. Each gets a different constraint:
+
+| Agent | Constraint |
+|-------|-----------|
+| Agent 1 | Minimize interface — 1-3 entry points max |
+| Agent 2 | Maximize flexibility — many use cases and extension |
+| Agent 3 | Optimize for most common caller — default case trivial |
+| Agent 4 | Ports & adapters pattern (if cross-boundary) |
+
+Each outputs: interface signature, usage example, what it hides, dependency strategy, trade-offs.
+
+Present sequentially, compare in prose, give opinionated recommendation.
+
+### 5. Create GitHub Issue RFC
+
+Use `gh issue create` with template below. Don't ask for review.
+
+## Issue Template
+
+<issue-template>
+
+## Problem
+
+Architectural friction:
+- Which modules are shallow and tightly coupled
+- Integration risk in the seams
+- Why this makes the codebase harder to navigate/maintain
+
+## Proposed Interface
+
+- Interface signature (types, methods, params)
+- Usage example
+- What complexity it hides
+
+## Dependency Strategy
+
+- **In-process**: merged directly
+- **Local-substitutable**: tested with [specific stand-in]
+- **Ports & adapters**: port definition, production adapter, test adapter
+- **Mock**: mock boundary for external services
+
+## Testing Strategy
+
+- New boundary tests to write
+- Old shallow tests to delete
+- Test environment needs
+
+## Implementation Recommendations
+
+Durable guidance NOT coupled to file paths:
+- What the module should own
+- What it should hide
+- What it should expose
+- How callers migrate
+
+</issue-template>
+
+## Dependency Categories
+
+| Category | Description | Deepenable? |
+|----------|-------------|-------------|
+| In-process | Pure computation, no I/O | Always |
+| Local-substitutable | Has local test stand-ins (PGLite, in-memory FS) | If stand-in exists |
+| Remote but owned | Your services across network (Ports & Adapters) | Via port injection |
+| True external | Third-party (Stripe, Twilio) — mock at boundary | Via mock injection |
+
+## Testing Principle
+
+**Replace, don't layer.** Old unit tests on shallow modules are waste once boundary tests exist — delete them. Tests assert on observable outcomes through public interface, not internal state.

package/app/skills/architecture-decision/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: architecture-decision
+description: "Loaded when user asks about architecture decisions or architecture note writing"
+effort: medium
+user-invocable: false
+allowed-tools: Read, Write
+---
+
+# Architecture Decision Skill
+
+## Core Philosophy: "Everything is a Trade-off"
+There are no "best solutions", only solutions with the right set of trade-offs for the specific context.
+
+## Decision Making Process (RFD / RFC)
+1. **Context**: What is the problem? Why now?
+2. **Constraints**: Budget, Time, Skillset, Legacy.
+3. **Options**: Propose at least 3 viable options.
+4. **Trade-off Analysis**: Compare constraints vs options.
+5. **Recommendation**: Choose one and justify.
+
+## Trade-off Analysis Matrix (Template)
+
+| Feature | Option A (e.g. SQL) | Option B (e.g. NoSQL) | Option C (e.g. File) |
+|---------|---------------------|-----------------------|----------------------|
+| **Scalability** | Medium (Vertical) | High (Horizontal) | Low |
+| **Consistency** | Strong (ACID) | Eventual (BASE) | N/A |
+| **Complexity** | Low (Known) | Medium (New tech) | Low |
+| **Cost** | $$ | $$$ | $ |
+
+## Architecture Note
+When a decision is made, document it.
+
+```markdown
+# Architecture Note: Use PostgreSQL for Main Database
+
+## Status
+Accepted
+
+## Context
+We need a reliable, relational database for user data...
+
+## Decision
+We will use PostgreSQL 16.
+
+## Consequences
+- Positive: ACID compliance, rich ecosystem.
+- Negative: Scaling writes requires sharding later.
+```
+
+## Critical Factors to Evaluate
+- **Reliability** (Availability, Fault tolerance)
+- **Scalability** (Throughput, Latency)
+- **Maintainability** (Simple vs Easy, Ecosystem)
+- **Security** (AuthN/Z, Encryption)
+- **Cost** (Infrastructure, License, Cognitive load)

package/app/skills/architecture-decision/templates/adr-template.md

@@ -0,0 +1,36 @@
+# Architecture Note: [Title]
+
+## Status
+
+[Draft | Accepted | Deprecated | Superseded]
+
+## Context
+
+[What is the issue that we're seeing that is motivating this decision or change?]
+
+## Decision
+
+[What is the change that we're proposing and/or doing?]
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Risks
+- [Risk 1 and mitigation]
+
+## Alternatives Considered
+
+### Option A: [Name]
+- Pros: [...]
+- Cons: [...]
+
+### Option B: [Name]
+- Pros: [...]
+- Cons: [...]