ai-playbook 1.0.0

package/roles/software-developer/api/checklist.md

@@ -0,0 +1,131 @@
+# API‑Development Checklists  
+
+A concise, reusable list of tasks that must be completed before, during, and after implementing any public API surface (REST, GraphQL, gRPC, or async inference endpoints) in the **Software‑Developer** role that works with **Claude‑Skills**.  
+Each checklist is written in GitHub‑flavoured Markdown task‑list syntax (`- [ ]` = pending, `- [x]` = done) so you can tick items directly in most editors or on GitHub.
+
+---  
+
+## 📦 0️⃣ Prerequisites (run once per change)
+
+- [ ] **Ticket ready** – Issue contains a clear title, acceptance criteria, and success metrics.  
+- [ ] **Context loaded** –  
+  - `context/engineering.md`  
+  - `projects/<PROJECT>/context.md`  
+- [ ] **Relevant skill files loaded** –  
+  - `skills/software-development/skill.md` (API Design)  
+  - `skills/qa/skill.md` (Testing)  
+  - `skills/security/skill.md` (Security)  
+  - `skills/performance/skill.md` (Performance)  
+- [ ] **Branch created** – `git checkout -b api/<JIRA_ID>-<short‑desc>` and pushed.  
+
+---  
+
+## ✍️ 1️⃣ Design & Specification
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | Draft an **OpenAPI (or GraphQL) schema** in `docs/openapi.yaml` (or `graphql/schema.graphql`). |
+| [ ] | Add a **design note** (`docs/design/<TICKET_ID>-<short>.md`) that states: <br/> • endpoint purpose <br/> • request/response contract <br/> • authentication/authorization expectations <br/> • error handling (RFC 7807) <br/> • any relevant **skill‑map** rows (e.g., *API Design – Proficiency 5*). |
+| [ ] | Verify **naming conventions** (kebab‑case for URLs, snake_case for fields, versioned under `/v1/`). |
+| [ ] | Confirm **authentication** requirements – API‑Key header `X-Api-Key` must be documented and enforced. |
+| [ ] | Document **rate‑limit** expectations in the spec and add a comment in the design note. |
+| [ ] | Review **privacy / data‑ residency** rules – ensure no PII is exposed unintentionally. |
+
+---  
+
+## 🛠️ 2️⃣ Implementation
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | Implement the handler **inside** the appropriate package (`src/<package>/api/v1/`). |
+| [ ] | Keep the function **pure** – no hidden side‑effects outside the returned response. |
+| [ ] | Validate **input** using Pydantic (or GraphQL validation) – reject malformed payloads early. |
+| [ ] | Re‑use **shared utilities** (`src/myapp/api/v1/utils.py`) – e.g., `parse_api_key()`, `rate_limit_exceeded()`. |
+| [ ] | Add **inline comments** only for non‑obvious logic; do **not** comment every line. |
+| [ ] | Apply **type hints** (`-> dict`, `-> User`) and run `mypy` with `--strict`. |
+| [ ] | Run **local linting** (`ruff check .`) and fix all violations. |
+| [ ] | Add **unit tests** for pure functions and **integration tests** for the full request‑response cycle. |
+| [ ] | Ensure **code coverage** for new lines ≥ 80 % (checked by CI). |
+| [ ] | Run **security scans** locally (`bandit -r . && safety check -r .`) – fix any HIGH severity findings. |
+| [ ] | Add **performance sanity** check – verify latency < target ms for a mock payload (use `time.perf_counter`). |
+| [ ] | Write **docstrings** that follow the Google/NumPy style and include `@param`/`@return` tags. |
+| [ ] | Register the new endpoint in the **router** (`src/myapp/api/v1/router.py`) and update the **OpenAPI spec** accordingly. |
+
+---  
+
+## 🧪 3️⃣ Testing & Quality Gates
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | **Unit tests** cover all new/modified functions (≥ 80 % line coverage). |
+| [ ] | **Integration tests** exercise the full HTTP flow (use `httpx` or `testclient`). |
+| [ ] | **Contract tests** validate request/response schemas against the OpenAPI spec (`schemathesis` or similar). |
+| [ ] | **Model‑specific validation** (if the endpoint calls Claude) runs `scripts/model_validation.py` – check accuracy >= target and latency ≤ target. |
+| [ ] | **Mutation testing** (optional) passes on changed files (`mutmut run`). |
+| [ ] | **Static security analysis** passes (`bandit`, `safety`). |
+| [ ] | **Performance benchmark** runs against a local staging of the endpoint; exit status must be 0 if latency ≤ SLA. |
+| [ ] | All CI stages **pass** on the first push (no re‑run required). |
+| [ ] | Test data is **mocked** or **seeded**; no real secrets are written to logs. |
+
+---  
+
+## 📦 4️⃣ Code Review & Refactor
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | Open a **Pull Request** with: <br/> • Title prefixed by the ticket ID (`Fix #1234 – Add user create endpoint`) <br/> • Description linking to the design note and acceptance criteria <br/> • Checklist items ticked (copy‑paste from this file). |
+| [ ] | Request **at least two reviewers**: one senior engineer and one domain expert (e.g., AI/ML). |
+| [ ] | Address all **review comments** – fix lint failures, update tests, or adjust documentation as needed. |
+| [ ] | Re‑run **CI** after each push; CI must end with a green check before merging. |
+| [ ] | Perform a **final refactor pass** to eliminate dead code, debug prints, or temporary TODOs. |
+| [ ] | Verify **test suite** still passes after refactor. |
+| [ ] | Ensure **no new third‑party dependencies** are introduced without approval. |
+| [ ] | Confirm **code style** adheres to the project’s `.style.yaml` (e.g., max line length, import ordering). |
+
+---  
+
+## 📚 5️⃣ Documentation Update
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | Update **API reference docs** – add the new endpoint description to `docs/api_reference.md`. |
+| [ ] | Regenerate **OpenAPI spec** (`scripts/generate-openapi.sh`) and commit the updated `docs/openapi.yaml`. |
+| [ ] | Add **examples** for request/response payloads in the design note and in the README. |
+| [ ] | Commit a **runbook entry** for the new endpoint (`ops/runbooks/<endpoint>.md`) covering: <br/> • health‑check URL <br/> • scaling limits <br/> • rollback steps. |
+| [ ] | Link the new documentation from the **ticket** and **PR description**. |
+| [ ] | Ensure the **CHANGELOG.md** entry mentions the new feature (semantic version bump). |
+
+---  
+
+## 🚀 6️⃣ Deployment & Release
+
+| ✅ | Checklist Item |
+|----|----------------|
+| [ ] | Bump the **version** in `pyproject.toml` / `requirements.txt` and add a Git tag (`vX.Y.Z`). |
+| [ ] | Build the Docker image (`docker build -t mycompany/myapp:<tag> .`) and push to the registry. |
+| [ ] | Update the **Helm values** (`helm/myapp/values.yaml`) with the new image tag and any config changes. |
+| [ ] | Submit a **Helm PR** and have it approved; CI will run `helm lint` and `helm unittest`. |
+| [ ] | Trigger the **Canary Deployment** (Argo Rollouts) – verify 5 % traffic shift. |
+| [ ] | Monitor **Prometheus** metrics (`request_latency_seconds`, `error_rate`, `gpu_utilization`) for the required stability window. |
+| [ ] | Once health checks pass, **promote to production** (either automatic rollout or manual `helm upgrade`). |
+| [ ] | Create a **release note** entry in `CHANGELOG.md` and post a summary to `#releases`. |
+| [ ] | Close the original ticket with status **Done** and transition it to the *Release* board column. |
+
+---  
+
+## ✅ 7️⃣ Final Verification (Success Criteria)
+
+| Requirement | Checklist Item |
+|-------------|----------------|
+| **Problem solved** | ✅ All acceptance criteria listed in the ticket are met (verify via test output). |
+| **Conforms to conventions** | ✅ Code style, naming, and directory layout follow the project’s standards (checked by lint & reviewers). |
+| **Production‑ready** | ✅ Image builds, Helm chart validates, and deployment succeeds without errors. |
+| **Tests present** | ✅ Unit, integration, contract, and performance tests all pass. |
+| **Technical debt minimized** | ✅ No new TODOs, dead code, or duplicated logic was introduced. |
+| **Decisions explained** | ✅ Design note and PR description clearly articulate why the chosen approach was taken (refer to relevant `skill-map.md` rows). |
+
+If any red ❌ appears, return to the appropriate earlier step (usually **Design**, **Implement**, or **Test**) until the issue is resolved.
+
+---  
+
+## 📌 Quick Reference (Condensed)

package/roles/software-developer/api/examples.md

@@ -0,0 +1,459 @@
+# API Examples
+
+This document contains production-ready API examples for the public REST API exposed by the AI-enhanced microservice.
+
+All endpoints are versioned under **`/v1`**.
+
+The OpenAPI specification is located at:
+
+```text
+docs/openapi.yaml
+```
+
+---
+
+# API Requirements
+
+Every request must include:
+
+* `X-Api-Key`
+* `Content-Type: application/json`
+* `Accept: application/json`
+
+API keys are automatically retrieved from the project's secret manager.
+
+All responses are JSON encoded.
+
+Errors follow **RFC 7807 (Problem Details)**.
+
+Rate limiting information is returned via:
+
+* `X-RateLimit-Limit`
+* `X-RateLimit-Remaining`
+
+---
+
+# 1. Base URL
+
+```
+https://api.mycompany.com/v1
+```
+
+---
+
+# Common Headers
+
+| Header       | Value                                         |
+| ------------ | --------------------------------------------- |
+| Content-Type | application/json                              |
+| Accept       | application/json                              |
+| X-Api-Key    | Secret retrieved from Vault (`myapp/api_key`) |
+
+---
+
+# 2. Create User
+
+## Endpoint
+
+```http
+POST /v1/users
+```
+
+---
+
+## Request
+
+```http
+POST /v1/users HTTP/1.1
+Host: api.mycompany.com
+Content-Type: application/json
+Accept: application/json
+X-Api-Key: <YOUR_API_KEY>
+```
+
+```json
+{
+  "email": "alice@example.com",
+  "first_name": "Alice",
+  "last_name": "Anderson",
+  "preferences": {
+    "notification_channel": "email",
+    "theme": "dark"
+  }
+}
+```
+
+---
+
+## Successful Response
+
+**201 Created**
+
+```json
+{
+  "user_id": "u_9f3a2c7b-5e1d-4b8e-9c33-71d9c1e5b6f2",
+  "email": "alice@example.com",
+  "full_name": "Alice Anderson",
+  "created_at": "2025-11-03T14:32:10Z",
+  "api_version": "v1"
+}
+```
+
+---
+
+## Error Responses
+
+| Status | Description                    |
+| ------ | ------------------------------ |
+| 400    | Missing required field `email` |
+| 401    | Invalid or missing API key     |
+| 429    | Rate limit exceeded            |
+| 500    | Internal server error          |
+
+---
+
+# 3. Retrieve User
+
+## Endpoint
+
+```http
+GET /v1/users/{user_id}
+```
+
+---
+
+## Request
+
+```http
+GET /v1/users/u_9f3a2c7b-5e1d-4b8e-9c33-71d9c1e5b6f2 HTTP/1.1
+Host: api.mycompany.com
+Accept: application/json
+X-Api-Key: <YOUR_API_KEY>
+```
+
+---
+
+## Response
+
+**200 OK**
+
+```json
+{
+  "user_id": "u_9f3a2c7b-5e1d-4b8e-9c33-71d9c1e5b6f2",
+  "email": "alice@example.com",
+  "first_name": "Alice",
+  "last_name": "Anderson",
+  "created_at": "2025-11-03T14:32:10Z",
+  "role": "standard",
+  "metadata": {
+    "last_login": "2025-11-02T09:15:44Z",
+    "device_count": 2
+  }
+}
+```
+
+---
+
+# 4. Update User Preferences
+
+## Endpoint
+
+```http
+PATCH /v1/users/{user_id}/preferences
+```
+
+---
+
+## Request
+
+```json
+{
+  "notification_channel": "push",
+  "theme": "light"
+}
+```
+
+---
+
+## Response
+
+```json
+{
+  "user_id": "u_9f3a2c7b-5e1d-4b8e-9c33-71d9c1e5b6f2",
+  "updated_preferences": {
+    "notification_channel": "push",
+    "theme": "light"
+  },
+  "updated_at": "2025-11-03T15:02:07Z"
+}
+```
+
+---
+
+# 5. Generate Text (Model as a Service)
+
+This endpoint runs the latest Claude model independently from CRUD operations.
+
+## Endpoint
+
+```http
+POST /v1/generate
+```
+
+---
+
+## Request
+
+```json
+{
+  "model": "claude-3-opus-2025-10",
+  "prompt": "Explain the difference between REST and GraphQL for a non-technical audience.",
+  "max_tokens": 250,
+  "temperature": 0.7,
+  "top_p": 0.9,
+  "metadata": {
+    "client_id": "c_7d4e9a2f",
+    "request_id": "req_4f6b9c1e"
+  }
+}
+```
+
+---
+
+## Successful Response
+
+```json
+{
+  "id": "gen_9c8b3f1a-2d7e-4a5c-bb71-3f9e5d6a7b1c",
+  "model": "claude-3-opus-2025-10",
+  "status": "completed",
+  "usage": {
+    "prompt_tokens": 35,
+    "completion_tokens": 172,
+    "total_tokens": 207
+  },
+  "output": "REST (Representational State Transfer) is an architectural style..."
+}
+```
+
+---
+
+## Error Responses
+
+| HTTP | Description               |
+| ---- | ------------------------- |
+| 400  | Missing prompt or model   |
+| 422  | Validation error          |
+| 429  | Inference queue full      |
+| 503  | Model service unavailable |
+
+---
+
+# 6. cURL Examples
+
+Store the API key:
+
+```bash
+export MYAPP_API_KEY=<your-secret>
+```
+
+---
+
+## Create User
+
+```bash
+curl -X POST https://api.mycompany.com/v1/users \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: $MYAPP_API_KEY" \
+  -d '{
+        "email":"bob@example.org",
+        "first_name":"Bob",
+        "last_name":"Baker"
+      }' | jq
+```
+
+---
+
+## Get User
+
+```bash
+curl -X GET https://api.mycompany.com/v1/users/<ID> \
+  -H "Accept: application/json" \
+  -H "X-Api-Key: $MYAPP_API_KEY" | jq
+```
+
+---
+
+## Generate Text
+
+```bash
+curl -X POST https://api.mycompany.com/v1/generate \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: $MYAPP_API_KEY" \
+  -d @examples/generate_request.json | jq
+```
+
+---
+
+# 7. OpenAPI Example
+
+```yaml
+openapi: 3.1.0
+
+info:
+  title: MyCompany AI Service API
+  version: 1.0.0
+
+paths:
+  /v1/users:
+    post:
+      summary: Create a new user account
+
+      requestBody:
+        required: true
+
+        content:
+          application/json:
+
+            schema:
+              $ref: '#/components/schemas/CreateUserRequest'
+
+      responses:
+
+        '201':
+          description: User created
+
+        '400':
+          description: Bad Request
+
+        '401':
+          description: Unauthorized
+
+        '429':
+          description: Too Many Requests
+```
+
+The complete specification is available at:
+
+```text
+docs/openapi.yaml
+```
+
+Generate SDKs using:
+
+```bash
+openapi-generator generate \
+    -i docs/openapi.yaml \
+    -g python \
+    -o src/sdk/python
+```
+
+---
+
+# 8. Python SDK Example
+
+```python
+import os
+
+from mycompany_api import ApiClient, Configuration
+from mycompany_api.models import CreateUserRequest
+from mycompany_api.models import GenerateRequest
+
+API_KEY = os.getenv("MYAPP_API_KEY")
+
+cfg = Configuration()
+cfg.api_key["X-Api-Key"] = API_KEY
+
+client = ApiClient(cfg)
+
+# Create User
+
+user = CreateUserRequest(
+    email="carol@example.net",
+    first_name="Carol",
+    last_name="Clarke"
+)
+
+api = MyCompanyApi.ApiClient(client)
+
+response = api.create_user(
+    create_user_request=user
+)
+
+print(response.user_id)
+
+# Generate Text
+
+request = GenerateRequest(
+    model="claude-3-opus-2025-10",
+    prompt="Write a haiku about cloud computing.",
+    max_tokens=100,
+    temperature=0.8
+)
+
+result = api.generate_text(
+    generate_request=request
+)
+
+print(result.output)
+```
+
+---
+
+# 9. Common Issues
+
+| Problem                 | Likely Cause               | Resolution                       |
+| ----------------------- | -------------------------- | -------------------------------- |
+| 401 Unauthorized        | Missing or invalid API key | Verify `X-Api-Key` header        |
+| 429 Too Many Requests   | Rate limit exceeded        | Honor `Retry-After` header       |
+| 503 Service Unavailable | Model service saturated    | Retry using exponential backoff  |
+| Missing `created_at`    | Older API version          | Use `/v1` endpoint               |
+| JSON Decode Error       | HTML error page returned   | Inspect Problem Details response |
+
+---
+
+# 10. Extending the API
+
+When adding a new endpoint:
+
+1. Add the handler under:
+
+```text
+src/myapp/api/v1/
+```
+
+2. Update:
+
+```text
+docs/openapi.yaml
+```
+
+3. Create a design document:
+
+```text
+docs/design/<ticket-id>-<feature>.md
+```
+
+4. Implement the endpoint following the existing request and response patterns.
+
+5. Add unit tests.
+
+```text
+tests/unit/
+```
+
+6. Add integration tests.
+
+```text
+tests/integration/api/
+```
+
+7. Validate the OpenAPI schema.
+
+```bash
+scripts/validate-openapi.sh
+```
+
+8. Open a Pull Request.
+
+9. Follow the Software Development workflow and checklist before merging.

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

@@ -0,0 +1,26 @@
+# Authentication
+
+Use this packet when work identifies users, services, devices, or workloads.
+Authentication answers: "Who is calling?"
+
+## Scope
+
+- Login, signup, logout, and session lifecycle.
+- Password, passkey, SSO, OAuth, OIDC, API key, and service-token flows.
+- Token creation, validation, refresh, revocation, and rotation.
+- Identity-provider integration and account linking.
+
+## Standards
+
+- Prefer established identity providers and audited libraries.
+- Store only salted password hashes when passwords are unavoidable.
+- Use short-lived access tokens and controlled refresh flows.
+- Bind sessions to explicit expiry, revocation, and rotation rules.
+- Never log credentials, tokens, cookies, authorization headers, or recovery codes.
+
+## Related Files
+
+- `../authorization/` for permissions after identity is established.
+- `../api/` for endpoint contract and authentication documentation.
+- `../logging/` for safe auth event logging.
+- `skills/security/` for secret and credential handling.

package/roles/software-developer/authentication/checklists.md

@@ -0,0 +1,22 @@
+# Authentication Checklists
+
+## Design
+
+- [ ] Identify each actor type: user, service, admin, webhook, or job.
+- [ ] Define credential type, token lifetime, refresh behavior, and revocation path.
+- [ ] Document account recovery, lockout, rate limit, and MFA expectations.
+- [ ] Confirm identity-provider configuration and redirect/callback constraints.
+
+## Implementation
+
+- [ ] Use approved auth libraries or platform primitives.
+- [ ] Validate issuer, audience, expiry, signature, and nonce where applicable.
+- [ ] Protect cookies with secure, httpOnly, sameSite, and scoped path settings.
+- [ ] Add brute-force and credential-stuffing protections.
+- [ ] Keep secrets in the approved secret manager.
+
+## Verification
+
+- [ ] Test success, invalid credential, expired token, revoked token, and replay cases.
+- [ ] Verify no credential material appears in logs, errors, traces, or metrics.
+- [ ] Confirm logout and revocation invalidate the intended sessions or tokens.

package/roles/software-developer/authentication/examples.md

@@ -0,0 +1,32 @@
+# Authentication Examples
+
+## Token Validation Shape
+
+```python
+def authenticate_request(token: str) -> Principal:
+    claims = token_validator.validate(
+        token,
+        issuer=settings.auth_issuer,
+        audience=settings.auth_audience,
+    )
+    return Principal(
+        subject=claims["sub"],
+        tenant_id=claims.get("tenant_id"),
+        scopes=set(claims.get("scope", "").split()),
+    )
+```
+
+## Safe Auth Log
+
+```python
+logger.info(
+    "Authentication failed",
+    extra={
+        "event": "auth.authentication.failed",
+        "reason": "expired_token",
+        "request_id": request_id,
+    },
+)
+```
+
+The log explains the failure without storing the token or authorization header.

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

@@ -0,0 +1,26 @@
+# Authorization
+
+Use this packet when deciding whether an authenticated actor may perform an
+action. Authorization answers: "What is this caller allowed to do?"
+
+## Scope
+
+- Role-based, attribute-based, relationship-based, and policy-based access.
+- Tenant boundaries and resource ownership checks.
+- Admin actions, impersonation, delegation, and break-glass flows.
+- Permission changes, audit trails, and access review support.
+
+## Standards
+
+- Enforce authorization server-side on every protected operation.
+- Keep policy decisions explicit and testable.
+- Deny by default when identity, tenant, ownership, or policy state is unclear.
+- Avoid trusting client-side role flags.
+- Audit sensitive grants, revocations, and privileged actions.
+
+## Related Files
+
+- `../authentication/` for identity establishment.
+- `../api/` for endpoint-level access contracts.
+- `../logging/` for audit event expectations.
+- `skills/security/` for least-privilege design.