ai-playbook 1.0.0

package/roles/software-developer/examples.md

@@ -0,0 +1,378 @@
+# Software‑Development Role – Example Scenarios & Code Snippets
+> The purpose of this document is to provide ready‑to‑copy examples that illustrate the expectations outlined in **role.md** and the **checklists.md**.  
+> Use these as templates, reference implementations, or starting points for new work items.
+
+---  
+
+## Table of Contents
+1. [Code‑Style & Project Conventions](#code-style--project-conventions)  
+2. [Typical Module Structure](#typical-module-structure)  
+3. [Common Design Patterns](#common-design-patterns)  
+4. [API Design (REST & GraphQL)](#api-design--rest--graphql)  
+5. [Testing Samples](#testing-samples)  
+6. [CI / Build Snippets](#ci--build-snippets)  
+7. [Observability & Logging](#observability--logging)  
+8. [Security Practices](#security-practices)  
+9. [Deployment (Docker + Helm)](#deployment--docker--helm)  
+10. [Documentation Boilerplate](#documentation-boilerplate)  
+
+---  
+
+## 1️⃣ Code‑Style & Project Conventions
+### Python (PEP‑8 + project specific)
+```python
+# src/myapp/utils.py
+"""Utility helpers – keep private functions prefixed with '_'."""
+from __future__ import annotations
+
+from typing import Iterable, List
+
+def chunk(iterable: Iterable[int], size: int) -> List[List[int]]:
+    """Yield successive *size*‑sized chunks from *iterable*."""
+    it = iter(iterable)
+    while True:
+        chunk = list(itertools.islice(it, size))
+        if not chunk:
+            break
+        yield chunk
+
+def _private_helper(x: int) -> int:
+    """Internal helper – not part of the public API."""
+    return x * 2
+
+Follow the project config:
+
+ruff for linting, mypy for static typing.
+pre‑commit hooks run on every commit (pre-commit run --all-files).
+Naming Conventions
+Element	Recommended Pattern
+Modules	src/<package>/
+Packages	src/<package_name>/ (all lower‑case)
+Public functions	snake_case
+Private helpers	_leading_underscore
+Classes	PascalCase
+Tests	tests/test_<module>_<feature>.py
+2️⃣ Typical Module Structure
+src/
+└─ myapp/
+   ├─ __init__.py
+   ├─ api/
+   │   ├─ __init__.py
+   │   └─ v1/
+   │       ├─ __init__.py
+   │       └─ users.py
+   ├─ core/
+   │   ├─ __init__.py
+   │   └─ service.py
+   ├─ db/
+   │   ├─ __init__.py
+   │   └─ models.py
+   ├─ main.py
+   └─ config/
+       └─ settings.py
+Why?
+
+Separation of concerns (API, core business logic, persistence).
+Makes it easy to load context (projects/<proj>/context.md) and locate related skills.
+3️⃣ Common Design Patterns
+3.1. Repository Pattern (Data Access)
+# src/myapp/db/repositories/user_repo.py
+from sqlalchemy.ext.asyncio import AsyncSession
+from myapp.db.models import User  # SQLAlchemy ORM model
+
+class UserRepository:
+    """Async repository encapsulating CRUD operations for users."""
+
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def get_by_id(self, user_id: int) -> User | None:
+        result = await self.session.get(User, user_id)
+        return result
+
+    async def list_active(self) -> list[User]:
+        stmt = select(User).where(User.is_active == True)
+        result = await self.session.execute(stmt)
+        return result.scalars().all()
+3.2. Strategy Pattern (Pluggable Algorithms)
+# src/myapp/strategies/payments.py
+from abc import ABC, abstractmethod
+
+class PaymentStrategy(ABC):
+    @abstractmethod
+    async def charge(self, amount_cents: int, user_id: str) -> bool:
+        ...
+
+class StripePayment(PaymentStrategy):
+    async def charge(self, amount_cents: int, user_id: str) -> bool:
+        # call Stripe SDK …
+        return True
+4️⃣ API Design (REST & GraphQL)
+4.1. REST Endpoint – Create User
+# src/myapp/api/v1/users.py
+from fastapi import APIRouter, HTTPException, Depends
+from pydantic import BaseModel, EmailStr
+from myapp.db.repositories.user_repo import UserRepository
+
+router = APIRouter(prefix="/v1/users", tags=["users"])
+
+class CreateUserRequest(BaseModel):
+    email: EmailStr
+    name: str | None = None
+    # ... other fields
+
+@router.post("/", status_code=201)
+async def create_user(payload: CreateUserRequest,
+                      repo: UserRepository = Depends()) -> dict:
+    # Convert request → domain entity
+    new_user = User(email=payload.email, name=payload.name)
+    await repo.session.add(new_user)
+    await repo.session.commit()
+    await repo.session.refresh(new_user)
+
+    return {"id": new_user.id, "email": new_user.email, "name": new_user.name}
+Key points
+
+Validate input via Pydantic.
+Return HTTP 201 on successful creation.
+Use dependency injection for repository.
+4.2. GraphQL Resolver (Ariadne example)
+# src/myapp/graphql/resolvers.py
+from ariadne import mutation, make_executable_schema
+from myapp.api.v1.users import create_user
+
+@mutation("createUser")
+async def create_user(_, info, **kwargs):
+    # Resolve DB repo via DI or info.context
+    repo = info.context["user_repo"]
+    user = await repo.create(**kwargs)  # re‑use same logic as REST
+    return {"user": user}
+5️⃣ Testing Samples
+5.1. Unit Test – Function with Pure Logic
+# tests/unit/test_utils.py
+import pytest
+from myapp.utils import chunk
+
+@pytest.mark.parametrize(
+    "data,size,expected",
+    [
+        ([1, 2, 3, 4, 5], 2, [[1, 2], [3, 4], [5]]),
+        ([], 3, []),
+        ([1], 1, [[1]]),
+    ],
+)
+def test_chunk(data, size, expected):
+    assert chunk(data, size) == expected
+5.2. Integration Test – API End‑to‑End
+# tests/integration/test_user_api.py
+import httpx
+import pytest
+from myapp.api.v1.users import router
+from fastapi.testclient import TestClient
+
+@pytest.fixture
+def client():
+    with TestClient(router) as c:
+        yield c
+
+@pytest.mark.asyncio
+async def test_create_user_success(client):
+    payload = {"email": "alice@example.com", "name": "Alice"}
+    resp = client.post("/users", json=payload)
+    assert resp.status_code == 201
+    data = resp.json()
+    assert data["email"] == payload["email"]
+    assert "id" in data
+5.3. Property‑Based Test with hypothesis
+# tests/property/test_repo.py
+from hypothesis import given, strategies as st
+import pytest
+from myapp.db.repositories.user_repo import UserRepository
+from myapp.db.models import User, async_session_maker
+
+@given(st.integers(min_value=1, max_value=1_000_000))
+def test_user_id_is_positive(id_: int):
+    assert id_ > 0
+6️⃣ CI / Build Snippets
+6.1. GitHub Actions – Full Pipeline
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install -r dev-requirements.txt
+          pre-commit install
+      - name: Lint & type check
+        run: |
+          ruff check .
+          mypy .
+      - name: Run tests
+        run: |
+          pytest --cov=src --cov-report=xml
+      - name: Security scan
+        run: |
+          bandit -r .
+          safety check -r .
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+          with:
+            files: coverage.xml
+7️⃣ Observability & Logging
+7.1. Structured JSON Logging (Python structlog)
+# src/myapp/logging_config.py
+import structlog
+import logging
+
+def configure_logging():
+    logging.basicConfig(
+        format="%(message)s",
+        level=logging.INFO,
+    )
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.TimeStamper(fmt="iso"),
+            structlog.processors.JSONRenderer(),
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
+    )
+Usage inside code:
+
+import structlog
+log = structlog.get_logger()
+log.info("user_created", user_id=user.id, email=user.email, latency_ms=12)
+7.2. Prometheus Metrics (aioxray)
+# src/myapp/metrics.py
+from prometheus_client import Counter, Histogram
+
+INFERENCES = Histogram(
+    "inference_latency_seconds",
+    "Latency of inference calls",
+    buckets=(0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5),
+)
+CALLS_TOTAL = Counter("inference_calls_total", "Total number of inference calls")
+Metric registration happens at module import; expose a helper:
+
+async def infer(payload: dict) -> dict:
+    with INFERENCES.time():
+        CALLS_TOTAL.inc()
+        # actual inference logic …
+        return result
+8️⃣ Security Practices
+8.1. Secret Management (Vault example)
+# .env (never commit!)
+VAULT_ADDR=https://vault.mycompany.com
+VAULT_TOKEN=${{ secrets.VAULT_TOKEN }}
+Python wrapper:
+
+# src/myapp/security/vault.py
+import hvac
+from myapp.config import Settings
+
+_client = hvac.Client(
+    url=Settings.VAULT_ADDR,
+    token=Settings.VAULT_TOKEN,
+)
+
+def get_secret(path: str, key: str) -> str | None:
+    secret = _client.secrets.kv.v2.read_secret_version(path=path)
+    return secret["data"]["data"].get(key)
+8.2. OWASP Security Headers (FastAPI)
+# src/myapp/api/common.py
+from fastapi.middleware import Middleware
+from fastapi.middleware.security import SecurityMiddleware
+
+def get_app():
+    app = FastAPI(middleware=[
+        SecurityMiddleware(
+            https_redirect=True,
+            hsts_max_age=31536000,
+            sts_include_subdomains=True,
+            sts_preload=True,
+            force_https=True,
+            allowed_hosts=["api.mycompany.com"],
+        ),
+        # … other middleware
+    ])
+    return app
+9️⃣ Deployment – Docker + Helm
+9.1. Multi‑Stage Dockerfile
+# Dockerfile
+# ---------- Build stage ----------
+FROM python:3.11-slim AS builder
+WORKDIR /app
+COPY pyproject.toml poetry.lock ./
+RUN pip install --no-cache-dir poetry && poetry config virtualenvs.in-project true \
+    && poetry install --no-interaction --no-ansi --only main
+
+# ---------- Runtime stage ----------
+FROM python:3.11-slim AS runtime
+WORKDIR /app
+COPY --from=builder /app/.venv /app/.venv
+ENV PATH="/app/.venv/bin:$PATH"
+COPY . .
+EXPOSE 8080
+CMD ["uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8080"]
+9.2. Helm values.yaml snippet
+# helm/myapp/values.yaml
+replicaCount: 3
+
+image:
+  repository: mycompany/myapp
+  tag: "v1.4.2"
+  pullPolicy: IfNotPresent
+
+service:
+  type: ClusterIP
+  port: 8080
+
+resources:
+  requests:
+    cpu: "200m"
+    memory: "256Mi"
+  limits:
+    cpu: "500m"
+    memory: "512Mi"
+
+autoscaling:
+  enabled: true
+  minReplicas: 2
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+🔟 Documentation Boilerplate
+10.1. README Section Template
+## Feature: <Short Title>
+
+**Purpose** – What problem does this feature solve?  
+**Stakeholders** – Primary users / consumers.  
+**Design Overview** – High‑level components and data flow (link to diagram).  
+**Endpoints** –  
+
+| Method | URL | Request Body | Response |
+|-------|-----|--------------|----------|
+| POST | `/v1/users` | `CreateUserRequest` | `{ "id": "...", "email": "..." }` |
+| GET  | `/v1/users/{id}` | — | `{ "id":"...", "name":"..." }` |
+
+**Testing** – How to run the unit / integration tests.  
+**Deployment** – Helm values to bump, CI steps.  
+**Rollback** – Steps to revert to previous version.  

package/roles/software-developer/frontend/README.md

@@ -0,0 +1,76 @@
+# Frontend Development Role
+
+Senior frontend developers build accessible, performant, tested, and maintainable user interfaces.
+
+## Overview
+
+This role guides frontend development across all frameworks and tools. It covers the complete lifecycle: component design, state management, testing, debugging, and monitoring.
+
+## Topics
+
+- **[Components](components/)** — Design reusable, composable components
+- **[State Management](state-management/)** — Manage data predictably and efficiently
+- **[Testing](testing/)** — Unit, integration, and e2e testing strategies
+- **[Code Quality](code-quality/)** — Format, lint, and maintain clean code
+- **[Performance](performance/)** — Measure, identify, and optimize bottlenecks
+- **[Accessibility](accessibility/)** — Build inclusive, WCAG-compliant interfaces
+- **[Debugging](debugging/)** — Debug systematically and efficiently
+- **[Logging & Observability](logging-observability/)** — Instrument code and monitor production
+- **[Examples](examples/)** - Larger frontend scenario templates and walkthroughs
+
+## Senior Developer Standards
+
+### Before Writing Code
+- [ ] Understand problem and requirements
+- [ ] Plan component structure
+- [ ] Identify state needs
+- [ ] Plan testing strategy
+
+### While Writing Code
+- [ ] Follow code quality standards
+- [ ] Think about edge cases
+- [ ] Consider accessibility
+- [ ] Add meaningful logging
+
+### After Writing Code
+- [ ] Write unit tests
+- [ ] Write integration tests
+- [ ] Verify code quality (lint, format)
+- [ ] Check accessibility
+- [ ] Test in browser
+- [ ] Verify performance
+- [ ] Code review with team
+
+### In Production
+- [ ] Monitor errors and performance
+- [ ] Act on observability data
+- [ ] Debug issues systematically
+- [ ] Share learnings with team
+
+## Framework-Agnostic Approach
+
+Guidance applies to React, Vue, Angular, Svelte, and vanilla JavaScript.
+Framework-specific details should live in project context or a future dedicated
+skill packet. Until then, keep this folder focused on framework-agnostic frontend
+engineering practices.
+
+## Success Criteria
+
+You're a senior frontend developer when:
+
+1. Components are testable, reusable, and performant
+2. State is minimal, explicit, and predictable
+3. Code is formatted, linted, and passes review
+4. Tests cover behavior, not just implementation
+5. Accessibility is built-in, not retrofitted
+6. Performance is measured and optimized
+7. Bugs are debugged systematically
+8. Production is instrumented and monitored
+9. You can onboard team members on these practices
+10. You improve practices based on learnings
+
+## Related Roles
+
+- `design-architect/` — Component library, design systems
+- `software-developer/` — Backend integration, API contracts
+- `qa/` — E2E test strategy, quality gates

package/roles/software-developer/frontend/accessibility/README.md

@@ -0,0 +1,136 @@
+# Accessibility (A11y)
+
+Senior frontend developers build accessible interfaces. Accessibility is not optional.
+
+## Why Accessibility Matters
+
+- 1 in 4 adults have disabilities
+- Accessible design benefits everyone
+- Legal requirement (WCAG, ADA)
+- Better UX for all users
+- Improves SEO
+
+## WCAG 2.1 Levels
+
+- **A** — basic accessibility
+- **AA** — enhanced accessibility (industry standard)
+- **AAA** — advanced accessibility (when feasible)
+
+Target AA for most projects.
+
+## Core Principles (POUR)
+
+### Perceivable
+- Content must be visible/perceivable
+- Provide text alternatives for images
+- Captions for audio/video
+- Color not only way to convey info
+
+### Operable
+- Keyboard navigable (no mouse required)
+- Enough time to read/interact
+- No seizure-inducing content
+- Skip to main content links
+
+### Understandable
+- Clear, plain language
+- Consistent navigation
+- Error prevention and messages
+- Clear labels on forms
+
+### Robust
+- Valid HTML
+- Proper semantic markup
+- Compatible with assistive tech
+
+## Implementation Practices
+
+### Semantic HTML
+- Use correct elements (`<button>` not `<div onclick>`)
+- `<nav>`, `<main>`, `<article>`, `<aside>`
+- `<h1>` - `<h6>` for headings (proper hierarchy)
+- `<form>`, `<label>`, `<input>` properly associated
+- `<table>` with `<thead>`, `<tbody>`, `<th>`
+
+### ARIA (Accessible Rich Internet Applications)
+- Enhance semantic HTML, not replace it
+- Use `role` for non-semantic elements
+- Use `aria-label` for icons/images
+- Use `aria-hidden="true"` for decorative elements
+- Use `aria-live` for dynamic content updates
+
+### Keyboard Navigation
+- Tab order logical and visible
+- Focus indicators visible
+- All interactive elements keyboard accessible
+- Escape key closes modals/popovers
+- Enter to submit forms, Space for buttons
+
+### Color & Contrast
+- Minimum 4.5:1 contrast for text
+- Don't rely on color alone
+- Test with contrast checkers
+- Consider colorblind users
+
+### Forms
+- Label all inputs explicitly
+- Group related inputs with `<fieldset>`
+- Validation error messages clear
+- Error states announced to screen readers
+- Required fields marked and announced
+
+### Images & Icons
+- Descriptive alt text (describes image, not "image of")
+- Decorative images: `alt=""`
+- Icon-only buttons: `aria-label`
+- SVGs: use `<title>` or `aria-label`
+
+## Testing for Accessibility
+
+### Automated Tools
+- axe DevTools (browser extension)
+- WAVE (WebAIM)
+- Lighthouse accessibility audit
+- ESLint plugins (jsx-a11y)
+
+### Manual Testing
+- Navigate with keyboard only
+- Test with screen reader (NVDA, JAWS, VoiceOver)
+- Zoom to 200% (responsive, readable)
+- Check with colorblind simulator
+- Test with browser zoom
+
+### User Testing
+- Include users with disabilities
+- Real accessibility feedback
+
+## Anti-Patterns
+
+- Using `<div>` for buttons/links
+- Decorative images with alt text
+- Relying on color alone
+- Focus indicators removed/hidden
+- Invalid HTML (breaks screen readers)
+- Inaccessible modals (focus not trapped)
+- No alt text for icons
+- Unmeaningful aria labels
+- Skip keyboard navigation
+
+## Accessibility Checklist
+
+Before shipping:
+- [ ] Semantic HTML used
+- [ ] Color contrast >= 4.5:1
+- [ ] Keyboard navigable
+- [ ] Alt text on images
+- [ ] Forms properly labeled
+- [ ] Focus indicators visible
+- [ ] Screen reader tested
+- [ ] axe audit passes
+- [ ] WCAG AA compliant
+
+## Related Guidance
+
+- `/code-quality` — semantic HTML standards
+- `/testing` — accessibility testing
+- `/components` — accessible component patterns