@softspark/ai-toolkit 1.0.0

package/app/skills/ci-cd-patterns/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: ci-cd-patterns
+description: "Loaded when user asks about CI/CD pipelines or deployment automation"
+effort: medium
+user-invocable: false
+---
+
+# CI/CD Patterns
+
+## GitHub Actions
+
+### Standard Pipeline
+```yaml
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+      - run: npm ci
+      - run: npm test -- --coverage
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.node-version }}
+          path: coverage/
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: "npm"
+      - run: npm ci
+      - run: npm run build
+```
+
+### Python CI
+```yaml
+name: Python CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "pip"
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy --strict src/
+      - run: pytest --cov=src --cov-report=xml
+```
+
+### Docker Build & Push
+```yaml
+  build-docker:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: ${{ github.ref == 'refs/heads/main' }}
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+## GitLab CI
+
+```yaml
+stages:
+  - lint
+  - test
+  - build
+  - deploy
+
+lint:
+  stage: lint
+  image: node:20
+  cache:
+    key: $CI_COMMIT_REF_SLUG
+    paths: [node_modules/]
+  script:
+    - npm ci
+    - npm run lint
+
+test:
+  stage: test
+  image: node:20
+  services:
+    - postgres:16
+  variables:
+    DATABASE_URL: "postgresql://postgres:postgres@postgres/test"
+  script:
+    - npm ci
+    - npm test
+
+build:
+  stage: build
+  image: docker:24
+  services:
+    - docker:24-dind
+  script:
+    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
+    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
+  only:
+    - main
+```
+
+## Docker Multi-stage Builds
+
+### Node.js
+```dockerfile
+# Stage 1: Dependencies
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --production
+
+# Stage 2: Build
+FROM node:20-alpine AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Stage 3: Production
+FROM node:20-alpine AS production
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+USER node
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+```
+
+### Python
+```dockerfile
+FROM python:3.12-slim AS builder
+WORKDIR /app
+COPY pyproject.toml .
+RUN pip install --no-cache-dir --target=/deps .
+
+FROM python:3.12-slim
+WORKDIR /app
+COPY --from=builder /deps /usr/local/lib/python3.12/site-packages
+COPY src/ ./src/
+USER nobody
+CMD ["python", "-m", "src.main"]
+```
+
+## Caching Strategies
+
+### npm/pnpm
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: ${{ runner.os }}-npm-
+```
+
+### pip
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/pip
+    key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+```
+
+### Docker Layer Caching
+```yaml
+- uses: docker/build-push-action@v5
+  with:
+    cache-from: type=gha
+    cache-to: type=gha,mode=max
+```
+
+## Kubernetes Deployment
+
+### Rolling Update
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api
+spec:
+  replicas: 3
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  template:
+    spec:
+      containers:
+        - name: api
+          image: ghcr.io/org/api:latest
+          readinessProbe:
+            httpGet:
+              path: /ready
+              port: 3000
+            initialDelaySeconds: 5
+          livenessProbe:
+            httpGet:
+              path: /live
+              port: 3000
+            initialDelaySeconds: 10
+```
+
+## Secret Management
+
+```yaml
+# GitHub Actions - use secrets
+env:
+  DATABASE_URL: ${{ secrets.DATABASE_URL }}
+  API_KEY: ${{ secrets.API_KEY }}
+
+# Never hardcode secrets in pipelines
+# Use OIDC for cloud provider auth (no long-lived credentials)
+- uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: arn:aws:iam::123456789:role/deploy
+    aws-region: us-east-1
+```
+
+## Release Automation
+
+### Semantic Release
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/github",
+    "@semantic-release/git"
+  ]
+}
+```
+
+### Conventional Commits for Auto-versioning
+| Prefix | Version Bump | Example |
+|--------|-------------|---------|
+| `fix:` | Patch (0.0.x) | `fix: resolve null pointer in auth` |
+| `feat:` | Minor (0.x.0) | `feat: add user search endpoint` |
+| `feat!:` / `BREAKING CHANGE:` | Major (x.0.0) | `feat!: change API response format` |
+
+## Anti-Patterns
+- Secrets in pipeline logs or environment dumps
+- No caching (slow builds)
+- Running tests only on main (should run on PRs)
+- Manual deployments to production
+- No rollback strategy
+- Skipping linting/type-checking in CI

package/app/skills/clean-code/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: clean-code
+description: "Loaded when user asks about clean code, naming, or code quality"
+effort: medium
+user-invocable: false
+---
+
+# Clean Code Skill
+
+## Core Principles
+
+### 1. Meaningful Names
+
+```python
+# Bad
+def calc(a, b):
+    return a * b
+
+# Good
+def calculate_total_price(unit_price: float, quantity: int) -> float:
+    return unit_price * quantity
+```
+
+### 2. Single Responsibility
+
+```python
+# Bad - does too much
+def process_user(user_data):
+    validate(user_data)
+    user = create_user(user_data)
+    send_welcome_email(user)
+    log_creation(user)
+    return user
+
+# Good - each function does one thing
+def create_user(user_data: UserData) -> User:
+    return User(**user_data)
+
+def onboard_user(user_data: UserData) -> User:
+    user = create_user(user_data)
+    send_welcome_email(user)
+    log_user_creation(user)
+    return user
+```
+
+### 3. DRY (Don't Repeat Yourself)
+
+```python
+# Bad
+def get_active_users():
+    return [u for u in users if u.status == "active"]
+
+def get_active_admins():
+    return [u for u in users if u.status == "active" and u.role == "admin"]
+
+# Good
+def filter_users(status: str | None = None, role: str | None = None) -> list[User]:
+    result = users
+    if status:
+        result = [u for u in result if u.status == status]
+    if role:
+        result = [u for u in result if u.role == role]
+    return result
+```
+
+---
+
+## Code Organization
+
+Keep modules focused. Order contents consistently: imports (stdlib, third-party, local), constants, public API, private helpers. Use clear visibility markers (underscore prefix in Python, access modifiers in other languages). Group related functionality into cohesive modules rather than dumping everything into a single file.
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| God class | Too many responsibilities | Split into smaller classes |
+| Long methods | Hard to understand | Extract methods |
+| Deep nesting | Complex control flow | Early returns, extract methods |
+| Magic numbers | Unclear meaning | Use named constants |
+| Bare except | Hides bugs | Catch specific exceptions |
+| Mutable defaults | Shared state bugs | Use `None` and create inside |
+
+---
+
+## Quality Checklist
+
+- [ ] Functions are small (<20 lines ideal)
+- [ ] Names are descriptive and consistent
+- [ ] Type hints on all public APIs
+- [ ] Docstrings on all public functions/classes
+- [ ] No magic numbers (use constants)
+- [ ] No hardcoded strings (use enums/constants)
+- [ ] Error handling is specific
+- [ ] Resources are properly cleaned up
+- [ ] No code duplication
+- [ ] Tests cover critical paths
+
+---
+
+## Language-Specific References
+
+For detailed patterns, type hints, linting configuration, and idiomatic code per language:
+
+- **Python:** type hints, docstrings, error handling, context managers, module/class structure, ruff/mypy config -- see [reference/python.md](reference/python.md)
+- **TypeScript:** strict tsconfig, ESLint setup, discriminated unions, type safety -- see [reference/typescript.md](reference/typescript.md)
+- **PHP:** PHPStan config, PSR-12, enums, constructor promotion -- see [reference/php.md](reference/php.md)
+- **Go:** gofmt, error handling, receiver naming, early returns -- see [reference/go.md](reference/go.md)
+- **Dart/Flutter:** null safety, named parameters, const constructors, dart analyze -- see [reference/dart.md](reference/dart.md)

package/app/skills/clean-code/reference/dart.md

@@ -0,0 +1,18 @@
+# Dart/Flutter Clean Code Patterns
+
+## Patterns
+
+```dart
+// Use dart analyze with strict rules
+// analysis_options.yaml: include: package:lints/recommended.yaml
+
+// Null safety
+String? getName() => _name;  // nullable return
+final name = getName() ?? 'default';  // null coalescing
+
+// Named parameters for clarity
+Widget buildCard({required String title, String? subtitle, VoidCallback? onTap}) { ... }
+
+// Use const constructors
+const EdgeInsets.all(16.0)
+```

package/app/skills/clean-code/reference/go.md

@@ -0,0 +1,23 @@
+# Go Clean Code Patterns
+
+## Patterns
+
+```go
+// Use gofmt (automatic), go vet, golangci-lint
+// Error handling - always check errors
+result, err := doSomething()
+if err != nil {
+    return fmt.Errorf("doSomething failed: %w", err)
+}
+
+// Use meaningful receiver names (not `this` or `self`)
+func (s *Service) Search(query string) ([]Result, error) { ... }
+
+// Return early to avoid deep nesting
+func validate(input string) error {
+    if input == "" {
+        return errors.New("input cannot be empty")
+    }
+    // ... continue with valid input
+}
+```

package/app/skills/clean-code/reference/php.md

@@ -0,0 +1,32 @@
+# PHP Clean Code Patterns
+
+## Configuration
+
+```yaml
+# phpstan.neon
+parameters:
+    level: 8   # max strictness
+    paths: [src]
+```
+
+## Patterns
+
+```php
+// Type declarations (PHP 8+)
+function calculatePrice(float $unitPrice, int $quantity): float {
+    return $unitPrice * $quantity;
+}
+
+// Use enums (PHP 8.1+)
+enum UserRole: string {
+    case Admin = 'admin';
+    case User = 'user';
+}
+
+// Follow PSR-12 coding standard
+// Use constructor promotion
+public function __construct(
+    private readonly string $name,
+    private readonly string $email,
+) {}
+```

package/app/skills/clean-code/reference/python.md

@@ -0,0 +1,180 @@
+# Python Clean Code Patterns
+
+## Type Hints (Required for Public APIs)
+
+```python
+from typing import Optional, List, Dict
+
+def search(
+    query: str,
+    limit: int = 10,
+    filters: Optional[Dict[str, str]] = None
+) -> List[Dict[str, any]]:
+    """Search the knowledge base.
+
+    Args:
+        query: Search query string
+        limit: Maximum results to return
+        filters: Optional field filters
+
+    Returns:
+        List of matching documents
+
+    Raises:
+        ValueError: If query is empty
+    """
+    if not query:
+        raise ValueError("Query cannot be empty")
+    ...
+```
+
+## Docstrings (Google Style)
+
+```python
+def calculate_relevance(
+    query: str,
+    document: str,
+    weights: dict[str, float]
+) -> float:
+    """Calculate relevance score between query and document.
+
+    Uses hybrid scoring combining BM25 and semantic similarity.
+
+    Args:
+        query: Search query
+        document: Document text
+        weights: Score weights {"bm25": 0.4, "semantic": 0.6}
+
+    Returns:
+        Relevance score between 0 and 1
+
+    Raises:
+        ValueError: If weights don't sum to 1.0
+
+    Example:
+        >>> calculate_relevance("test", "test doc", {"bm25": 0.5, "semantic": 0.5})
+        0.85
+    """
+```
+
+## Error Handling
+
+```python
+# Bad - bare except
+try:
+    result = risky_operation()
+except:
+    pass
+
+# Good - specific exceptions
+try:
+    result = risky_operation()
+except ConnectionError as e:
+    logger.error(f"Connection failed: {e}")
+    raise
+except ValueError as e:
+    logger.warning(f"Invalid value: {e}")
+    return default_value
+```
+
+## Context Managers
+
+```python
+# Bad
+file = open("data.txt")
+content = file.read()
+file.close()
+
+# Good
+with open("data.txt") as file:
+    content = file.read()
+
+# Custom context manager
+from contextlib import contextmanager
+
+@contextmanager
+def database_connection():
+    conn = create_connection()
+    try:
+        yield conn
+    finally:
+        conn.close()
+```
+
+## Module Structure
+
+```python
+"""Module docstring explaining purpose.
+
+This module provides functions for searching the knowledge base.
+"""
+
+# Standard library imports
+import logging
+from typing import Optional
+
+# Third-party imports
+import httpx
+from qdrant_client import QdrantClient
+
+# Local imports
+from .config import Settings
+from .models import Document
+
+# Module-level constants
+DEFAULT_LIMIT = 10
+LOGGER = logging.getLogger(__name__)
+
+# Public functions
+def search(query: str) -> list[Document]:
+    ...
+
+# Private functions (underscore prefix)
+def _normalize_query(query: str) -> str:
+    ...
+```
+
+## Class Structure
+
+```python
+class SearchService:
+    """Service for searching the knowledge base."""
+
+    def __init__(self, client: QdrantClient, settings: Settings):
+        """Initialize search service.
+
+        Args:
+            client: Qdrant client instance
+            settings: Application settings
+        """
+        self._client = client
+        self._settings = settings
+
+    def search(self, query: str, limit: int = 10) -> list[Document]:
+        """Search for documents."""
+        ...
+
+    def _validate_query(self, query: str) -> None:
+        """Validate search query (private method)."""
+        ...
+```
+
+## Linting Configuration
+
+### pyproject.toml
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]  # line too long (handled by formatter)
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+```

package/app/skills/clean-code/reference/typescript.md

@@ -0,0 +1,26 @@
+# TypeScript Clean Code Patterns
+
+## Configuration
+
+```json
+// tsconfig.json - strict mode
+{ "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true } }
+
+// .eslintrc - recommended rules
+{ "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended-type-checked", "prettier"] }
+```
+
+## Patterns
+
+```typescript
+// Type-safe function signatures
+function getUser(id: string): Promise<User | null> { ... }
+
+// Prefer `unknown` over `any`
+function parseData(raw: unknown): Result { ... }
+
+// Use discriminated unions
+type Result = { success: true; data: User } | { success: false; error: string };
+
+// Avoid: `any`, non-null assertions `!`, type casting `as` without guards
+```