@softspark/ai-toolkit 1.0.0

package/app/skills/design-engineering/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: design-engineering
+description: "Loaded when user asks about UI animations or CSS design craft"
+effort: medium
+user-invocable: false
+---
+
+# Design Engineering Skill
+
+Based on Emil Kowalski's design engineering philosophy — UI polish, component craftsmanship, and the compound value of invisible details.
+
+## Core Principles
+
+- **Taste is trainable.** Develops through studying exceptional work, reverse-engineering animations, and intentional practice.
+- **Invisible details create love.** Most UI refinements users never consciously register — but combined they produce something stunning.
+- **Beauty differentiates.** When functionality is table stakes, aesthetic excellence becomes genuine leverage.
+
+## Animation Decision Framework
+
+### Frequency determines approach
+
+| Usage Pattern | Strategy |
+|---|---|
+| 100+ daily | No animation |
+| Tens daily | Drastically reduce |
+| Occasional | Standard animation |
+| Rare/first-time | Add delight |
+
+**Never animate keyboard-initiated actions** — they repeat hundreds of times daily, making animation feel sluggish.
+
+### Purpose validation
+
+Every animation requires justification: spatial consistency, state indication, explanation, user feedback, or preventing jarring transitions. "It looks cool" alone disqualifies frequent interactions.
+
+### Easing rules
+
+| Direction | Easing | Why |
+|---|---|---|
+| Entering elements | `ease-out` | Immediate feedback |
+| On-screen movement | `ease-in-out` | Natural acceleration |
+| Hover/color changes | `ease` | Smooth transition |
+| Constant motion | `linear` | No acceleration |
+
+**Critical:** Abandon default CSS easings. Use custom curves:
+
+```css
+/* Punchy entrance */
+transition-timing-function: cubic-bezier(0.23, 1, 0.32, 1);
+```
+
+**Never use `ease-in`** — it delays initial movement exactly when attention peaks, making interfaces feel sluggish.
+
+### Duration guidelines
+
+| Element | Timing |
+|---|---|
+| Button press | 100-160ms |
+| Tooltips, small popovers | 125-200ms |
+| Dropdowns, selects | 150-250ms |
+| Modals, drawers | 200-500ms |
+
+UI animations should stay **under 300ms**. Speed perception matters as much as actual speed.
+
+## Component Patterns
+
+### Buttons must respond
+
+```css
+button:active {
+  transform: scale(0.97);
+}
+```
+
+Tactile feedback confirming interface responsiveness.
+
+### Never scale from zero
+
+```css
+/* Bad */
+.enter { transform: scale(0); opacity: 0; }
+
+/* Good — natural entrance */
+.enter { transform: scale(0.95); opacity: 0; }
+```
+
+Real-world objects don't vanish and reappear. Start from `scale(0.95)`.
+
+### Popovers scale from triggers
+
+```css
+.popover {
+  transform-origin: var(--radix-popover-content-transform-origin);
+}
+```
+
+Exception: modals keep centered origin (viewport-anchored, not trigger-anchored).
+
+### Tooltip optimization
+
+Initial tooltip includes delay; subsequent hovers skip both delay and animation via `[data-instant]` attribute — perceived speed without defeating accidental activation prevention.
+
+## Transform Mastery
+
+### Percentage translations
+
+```css
+/* Moves by own height — perfect for toasts, drawers */
+transform: translateY(100%);
+```
+
+No hardcoded pixel values needed.
+
+### Scale affects children
+
+Unlike `width`/`height`, `scale()` proportionally scales content, icons, and text. Intentional feature, not a bug.
+
+### 3D transforms
+
+```css
+.orbit {
+  transform-style: preserve-3d;
+}
+```
+
+Enables orbit animations and coin flips without JavaScript.
+
+## Clip-path Animation
+
+`clip-path: inset(top right bottom left)` creates rectangular clipping regions:
+
+### Tab color transitions
+
+Stack tab lists, clip the active copy, animate clip-path on change for seamless color shifting.
+
+### Hold-to-delete
+
+```css
+.delete-overlay {
+  clip-path: inset(0 100% 0 0);
+  transition: clip-path 2s linear;
+}
+.delete-button:active .delete-overlay {
+  clip-path: inset(0 0 0 0);
+}
+/* Release snaps back fast */
+.delete-overlay {
+  transition: clip-path 200ms ease-out;
+}
+```
+
+### Image reveals
+
+```css
+.reveal {
+  clip-path: inset(0 0 100% 0); /* hidden */
+}
+.reveal.visible {
+  clip-path: inset(0 0 0 0); /* revealed */
+}
+```
+
+### Comparison sliders
+
+Overlay images, clip top one by adjusting right inset based on drag position.
+
+## Performance Rules
+
+### GPU acceleration
+
+Only animate `transform` and `opacity` — these skip layout and paint. Animating `padding`, `margin`, `height`, `width` triggers full rendering pipeline.
+
+### CSS variables caveat
+
+Changing parent CSS variables recalculates styles on all children. Update `transform` directly on elements instead.
+
+### Framer Motion gotcha
+
+Shorthand properties (`x`, `y`, `scale`) use main-thread `requestAnimationFrame`, not GPU:
+
+```tsx
+// Bad — main thread
+<motion.div animate={{ x: 100 }} />
+
+// Good — GPU accelerated
+<motion.div animate={{ transform: "translateX(100px)" }} />
+```
+
+### CSS beats JavaScript
+
+CSS animations run off-thread and remain smooth during page loads. Framer Motion drops frames when browser is busy. Use CSS for predetermined animations; JavaScript for dynamic, interruptible ones.
+
+## Accessibility
+
+### Reduced motion
+
+Keep opacity and color transitions (aid comprehension). Remove movement and position animations:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+### Touch hover protection
+
+```css
+@media (hover: hover) and (pointer: fine) {
+  .card:hover {
+    transform: translateY(-2px);
+  }
+}
+```
+
+Touch triggers false hover positives — always gate hover animations.
+
+## Building Loved Components
+
+Five principles (from Sonner, 13M+ weekly downloads):
+
+1. **Developer experience first** — minimal setup friction, insert once, use globally
+2. **Excellent defaults** — ship beautifully configured out-of-box
+3. **Identity through naming** — a memorable name resonates
+4. **Invisible edge cases** — pause timers when hidden, handle pointer capture during drag
+5. **Transitions over keyframes** — rapid additions cause keyframe restart from zero; transitions retarget smoothly
+
+### Cohesion
+
+Animation personality should match component identity. Playful components can bounce; professional dashboards stay crisp.
+
+### Asymmetric timing
+
+Deliberate actions stay slow (2s linear for hold-to-delete), system responses snap fast (200ms ease-out for release).
+
+## Review Checklist
+
+| Issue | Resolution |
+|---|---|
+| `transition: all` | Specify properties: `transition: transform 200ms ease-out` |
+| `scale(0)` entries | Start `scale(0.95)` with `opacity: 0` |
+| `ease-in` on UI | Switch to `ease-out` or custom curve |
+| Popover `transform-origin: center` | Use trigger-aware CSS variable |
+| Animation on keyboard actions | Remove entirely |
+| Duration > 300ms UI | Reduce to 150-250ms |
+| Hover without media query | Add `@media (hover: hover) and (pointer: fine)` |
+| Keyframes on rapid triggers | Use CSS transitions |
+| Framer `x`/`y` under load | Use `transform: "translateX()"` |
+| Identical enter/exit speed | Make exit faster (e.g., 2s enter, 200ms exit) |
+| Simultaneous element appearance | Stagger 30-80ms between items |
+
+## Anti-Patterns
+
+- `transition: all` — animates unintended properties, hurts performance
+- `ease-in` on UI elements — delays feedback when attention peaks
+- Animating `height`/`width`/`margin` — triggers layout recalculation
+- Same duration for enter and exit — exits should be faster
+- Hover effects without `@media (hover: hover)` — breaks touch devices
+- Framer Motion shorthands under load — drops frames on main thread

package/app/skills/docker-devops/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: docker-devops
+description: "Loaded when user asks about Docker, containers, or DevOps patterns"
+effort: medium
+user-invocable: false
+---
+
+# Docker & DevOps Skill
+
+## Dockerfile Best Practices
+
+### Multi-Stage Build (Node.js)
+
+```dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+
+# Non-root user
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nextjs -u 1001
+
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+COPY --from=builder --chown=nextjs:nodejs /app/public ./public
+
+USER nextjs
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+### Multi-Stage Build (Python)
+
+```dockerfile
+# Build stage
+FROM python:3.12-slim AS builder
+WORKDIR /app
+RUN pip install --no-cache-dir poetry
+COPY pyproject.toml poetry.lock ./
+RUN poetry export -f requirements.txt -o requirements.txt
+
+# Production stage
+FROM python:3.12-slim
+WORKDIR /app
+
+# Non-root user
+RUN useradd -m -u 1000 appuser
+
+COPY --from=builder /app/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=appuser:appuser . .
+USER appuser
+
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+---
+
+## Docker Compose Patterns
+
+### Development Setup
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile.dev
+    volumes:
+      - .:/app
+      - /app/node_modules
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=development
+      - DATABASE_URL=postgresql://postgres:postgres@db:5432/app
+    depends_on:
+      - db
+      - redis
+
+  db:
+    image: postgres:16-alpine
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - "5432:5432"
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  postgres_data:
+```
+
+### Production Setup
+
+```yaml
+version: '3.8'
+
+services:
+  app:
+    image: ${REGISTRY}/app:${TAG}
+    restart: unless-stopped
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=${DATABASE_URL}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+    deploy:
+      resources:
+        limits:
+          cpus: '1'
+          memory: 512M
+```
+
+---
+
+## CI/CD Patterns
+
+### GitHub Actions (Node.js)
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    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 test
+      - run: npm run build
+
+  deploy:
+    needs: test
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Deploy to production
+        run: |
+          # Deploy commands
+```
+
+### GitHub Actions (Python)
+
+```yaml
+name: CI/CD
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Install dependencies
+        run: |
+          pip install poetry
+          poetry install
+      - name: Lint
+        run: poetry run ruff check .
+      - name: Type check
+        run: poetry run mypy .
+      - name: Test
+        run: poetry run pytest --cov
+```
+
+---
+
+## Infrastructure as Code
+
+### Terraform Basic Structure
+
+```
+infrastructure/
+├── main.tf
+├── variables.tf
+├── outputs.tf
+├── providers.tf
+├── modules/
+│   ├── networking/
+│   ├── compute/
+│   └── database/
+└── environments/
+    ├── dev/
+    ├── staging/
+    └── prod/
+```
+
+### Terraform Best Practices
+
+```hcl
+# variables.tf
+variable "environment" {
+  description = "Environment name"
+  type        = string
+  validation {
+    condition     = contains(["dev", "staging", "prod"], var.environment)
+    error_message = "Environment must be dev, staging, or prod."
+  }
+}
+
+# main.tf
+resource "aws_instance" "app" {
+  ami           = var.ami_id
+  instance_type = var.instance_type
+
+  tags = {
+    Name        = "${var.project}-${var.environment}-app"
+    Environment = var.environment
+    ManagedBy   = "terraform"
+  }
+}
+```
+
+---
+
+## Health Checks
+
+### HTTP Health Check
+
+```python
+# FastAPI
+@app.get("/health")
+async def health_check():
+    return {
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+        "version": settings.VERSION
+    }
+
+@app.get("/ready")
+async def readiness_check():
+    # Check database
+    try:
+        await db.execute("SELECT 1")
+    except Exception:
+        raise HTTPException(503, "Database not ready")
+
+    return {"status": "ready"}
+```
+
+### Docker Health Check
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
+  CMD curl -f http://localhost:3000/health || exit 1
+```
+
+---
+
+## Security Checklist
+
+- [ ] No secrets in Dockerfile or compose
+- [ ] Non-root user in container
+- [ ] Minimal base image (alpine, distroless)
+- [ ] Pinned image versions
+- [ ] Read-only filesystem where possible
+- [ ] Resource limits defined
+- [ ] Health checks configured
+- [ ] Logs to stdout/stderr

package/app/skills/docs/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: docs
+description: "Generate and update README, API docs, and architecture notes"
+user-invocable: true
+effort: high
+argument-hint: "[type: readme/api/architecture-note]"
+agent: documenter
+context: fork
+allowed-tools: Read, Write, Grep, Glob
+---
+
+# Generate Documentation
+
+$ARGUMENTS
+
+Generate or update documentation.
+
+## Usage
+
+```
+/docs [type] [target]
+```
+
+## What This Command Does
+
+1. **Analyzes** code structure
+2. **Extracts** documentation info
+3. **Generates** documentation files
+4. **Updates** existing docs
+
+## Documentation Types
+
+| Type | Description |
+|------|-------------|
+| `readme` | Generate/update README |
+| `api` | API documentation |
+| `architecture-note` | Architecture note |
+| `changelog` | Generate changelog |
+| `comments` | Add code comments |
+| `kb` | Knowledge base entry (enforces KB structure) |
+
+## KB Document Rules (MANDATORY)
+
+When creating or updating documents in the `kb/` directory, follow the `documentation-standards` knowledge skill (auto-loaded). Key rules:
+
+- **7 required frontmatter fields:** title, category, service, tags, created, last_updated, description
+- **5 valid categories:** reference, howto, procedures, troubleshooting, best-practices
+- **Category must match directory** (e.g., `category: howto` → `kb/howto/`)
+- **English only.** No exceptions.
+- **validate.sh rejects docs without valid frontmatter.**
+
+Full spec: see `app/skills/documentation-standards/SKILL.md`.
+
+## Templates
+
+### README Generation
+```markdown
+# [Project Name]
+
+[Auto-generated description]
+
+## Installation
+[Detected from package manager]
+
+## Usage
+[Extracted from code/examples]
+
+## API
+[Extracted from code]
+
+## License
+[Detected]
+```
+
+### Architecture Note Template
+```markdown
+# Architecture Note: [TITLE]
+
+## Status
+Proposed
+
+## Context
+[What is the issue?]
+
+## Decision
+[What was decided?]
+
+## Consequences
+[What are the results?]
+
+## Date
+[Today's date]
+```
+
+## Output Format
+
+```markdown
+## Documentation Report
+
+### Generated
+- [file 1]
+- [file 2]
+
+### Updated
+- [file 3]: [what changed]
+
+### Skipped
+- [file 4]: [reason]
+
+### Next Steps
+- [ ] Review generated docs
+- [ ] Add missing details
+- [ ] Commit changes
+```
+
+## Configuration
+
+Documentation settings in:
+- `.claude/settings.json`
+- Project's doc config
+
+## REVIEW BEFORE COMMIT
+
+Generated documentation should be reviewed.
+AI may miss context or make assumptions.
+
+## Documentation Inventory
+
+Run the bundled script to audit documentation coverage and find gaps:
+
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/doc-inventory.py .
+```
+
+## Parallel Documentation (large codebases)
+
+If the inventory script reports `doc_coverage_percent < 50` and the project has multiple modules, use Agent Teams for parallel documentation:
+
+```
+Create an agent team for documentation:
+- Teammate 1 (documenter): "Document the [module-1] directory. Generate docstrings for all public functions." Use Sonnet.
+- Teammate 2 (documenter): "Document the [module-2] directory. Generate docstrings for all public functions." Use Sonnet.
+- Teammate 3 (documenter): "Generate README sections: installation, usage, API reference." Use Opus.
+Teammates should NOT overlap — each owns their assigned scope.
+```