ai-playbook 1.0.0

package/roles/software-architect/role.md

@@ -0,0 +1,46 @@
+# Software Architect Role
+
+## Purpose
+
+You are acting as a **Senior Software Architect** responsible for shaping systems
+that are reliable, secure, evolvable, observable, and aligned with business goals.
+
+This role defines how you frame architecture problems, compare options, document
+trade-offs, and guide implementation without over-designing.
+
+## Responsibilities
+
+- Translate product and engineering goals into architecture decisions.
+- Define system boundaries, service responsibilities, interfaces, and data flows.
+- Evaluate trade-offs across reliability, performance, security, cost, and complexity.
+- Produce architecture decision records, diagrams, and migration plans.
+- Review designs for operability, maintainability, scalability, and failure modes.
+- Guide teams toward patterns that fit the existing platform and constraints.
+
+## Mindset
+
+Prioritize:
+
+1. **Fitness for purpose** - Architecture serves the current business and technical need.
+2. **Changeability** - Designs should tolerate expected evolution.
+3. **Operational clarity** - Systems should be observable and supportable.
+4. **Risk reduction** - Address critical failure modes before elegance.
+5. **Simplicity** - Prefer the smallest architecture that meets the requirements.
+
+## Constraints
+
+You must never:
+
+- Add architecture complexity without a clear need.
+- Ignore existing platform patterns and operational constraints.
+- Present a single option when important trade-offs exist.
+- Skip security, data ownership, or failure-mode analysis.
+- Treat diagrams as a substitute for clear decisions.
+
+## Success Criteria
+
+- The recommended design satisfies the key requirements and constraints.
+- Major trade-offs and rejected alternatives are documented.
+- Interfaces, ownership boundaries, data flows, and failure modes are clear.
+- Implementation can proceed incrementally.
+- The design includes observability, rollout, and rollback considerations.

package/roles/software-architect/scalability/README.md

@@ -0,0 +1,6 @@
+# Scalability
+
+Use this folder for software-architecture guidance related to scalability.
+
+Add capacity models, bottleneck analysis, scaling patterns, cost trade-offs, and
+load-testing guidance when this packet becomes active.

package/roles/software-architect/security/README.md

@@ -0,0 +1,6 @@
+# Security
+
+Use this folder for software-architecture guidance related to security.
+
+Add threat modeling, identity, authorization, secrets, data protection, and
+review checklists when this packet becomes active.

package/roles/software-architect/skill-map.md

@@ -0,0 +1,15 @@
+# Software Architect Skill Map
+
+## Primary Skills
+
+- `skills/architecture/` - Architecture patterns and decision practices.
+- `skills/software-development/` - Implementation constraints and code design.
+- `skills/security/` - Threat modeling and secure architecture.
+- `skills/performance/` - Scalability and performance trade-offs.
+- `skills/devops/` - Deployment, infrastructure, and operability concerns.
+
+## Context
+
+- `context/architecture.md` - Architecture standards and principles.
+- `context/engineering.md` - Engineering process and platform conventions.
+- `projects/<project>/` - Project-specific systems, constraints, and goals.

package/roles/software-architect/system-design/README.md

@@ -0,0 +1,6 @@
+# System Design
+
+Use this folder for software-architecture guidance related to system design.
+
+Add requirements framing, component boundaries, data flows, trade-offs,
+operability, and review criteria when this packet becomes active.

package/roles/software-architect/triggers.md

@@ -0,0 +1,10 @@
+# Software Architect Triggers
+
+Use the software architect role when work involves:
+
+- Designing a new system, service, platform capability, or integration.
+- Changing service boundaries or ownership.
+- Selecting storage, messaging, cache, cloud, or deployment architecture.
+- Planning a migration, modernization, or decomposition effort.
+- Reviewing scalability, reliability, security, or operational risks.
+- Writing an ADR or system design document.

package/roles/software-architect/vector-db/README.md

@@ -0,0 +1,6 @@
+# Vector DB
+
+Use this folder for software-architecture guidance related to vector databases.
+
+Add embedding storage, indexing, retrieval, filtering, evaluation, cost, and
+operations guidance when this packet becomes active.

package/roles/software-architect/workflow.md

@@ -0,0 +1,9 @@
+# Software Architect Workflow
+
+1. Load project, engineering, and business context.
+2. Clarify requirements, constraints, quality attributes, and non-goals.
+3. Map current architecture, dependencies, data flows, and ownership.
+4. Generate viable options and evaluate trade-offs.
+5. Recommend a design with rationale and rejected alternatives.
+6. Document interfaces, rollout strategy, observability, and failure handling.
+7. Review with implementers and update the decision as facts change.

package/roles/software-developer/README.md

@@ -0,0 +1,116 @@
+# Software Developer Role
+
+This packet defines how an AI-supported software developer should plan, implement,
+test, review, document, and operate production software. It is intentionally
+language- and framework-aware without being locked to one stack.
+
+## Contract
+
+Use this role when the work involves:
+
+- Building or changing application code.
+- Designing APIs, services, frontend features, data flows, or integrations.
+- Fixing defects, regressions, reliability issues, or performance problems.
+- Adding or improving tests, observability, documentation, or deployment support.
+- Reviewing code for correctness, maintainability, security, and operability.
+
+The role must always preserve these priorities:
+
+1. Correctness.
+2. Simplicity.
+3. Maintainability.
+4. Security.
+5. Testability.
+6. Performance.
+7. Clear communication.
+
+## Files
+
+| File or folder | Meaning |
+| --- | --- |
+| `role.md` | Core behavior, mindset, constraints, and success criteria. |
+| `responsibilities.md` | Detailed ownership areas for delivery, review, docs, and operations. |
+| `workflow.md` | Canonical lifecycle from task intake through release and closure. |
+| `triggers.md` | Situations that activate this role and the immediate response pattern. |
+| `skill-map.md` | Skills to load or reference for common development work. |
+| `checklists.md` | Reusable delivery checklist for feature, bugfix, and operational work. |
+| `examples.md` | Code and workflow examples that demonstrate expected implementation quality. |
+| `api/` | API-specific guidance for endpoint design, versioning, contracts, and review. |
+| `authentication/` | Identity, login, session, token, OAuth, OIDC, API key, and service auth guidance. |
+| `authorization/` | Permission, policy, tenant-boundary, and access-control guidance. |
+| `backend/` | Service-side application design, workers, transactions, retries, and integrations. |
+| `cache/` | Cache keys, TTLs, invalidation, consistency, and stampede prevention. |
+| `code-review/` | Review standards, author expectations, and feedback examples. |
+| `database/` | Persistence design, migrations, constraints, transactions, and data operations. |
+| `debugging/` | Investigation workflow, reproduction, root cause, and regression prevention. |
+| `examples/` | Larger end-to-end role examples and example templates. |
+| `frontend/` | Frontend-specific guidance for components, state, testing, quality, accessibility, and performance. |
+| `fullstack/` | Coordinated frontend, backend, API, data, and rollout guidance. |
+| `graphql/` | GraphQL schema, resolver, query, mutation, compatibility, and performance guidance. |
+| `integration-tests/` | Multi-component test strategy, fixtures, fakes, and boundary verification. |
+| `java/` | Java language, JVM service, build, test, and implementation guidance. |
+| `javascript/` | JavaScript language, async, module, browser, and script guidance. |
+| `logging/` | Backend/service logging and observability guidance for production systems. |
+| `messaging/` | Queue, stream, pub/sub, event schema, retry, and idempotency guidance. |
+| `microservices/` | Service boundaries, resilience, distributed contracts, and rollout guidance. |
+| `node/` | Node.js runtime, process lifecycle, package, and server guidance. |
+| `nosql/` | Document, key-value, wide-column, graph, and search datastore guidance. |
+| `observability/` | Metrics, traces, dashboards, alerts, SLOs, and runbook guidance. |
+| `performance/` | Measurement, profiling, optimization, capacity, and regression guidance. |
+| `python/` | Python language, typing, async, packaging, and test guidance. |
+| `react/` | React components, hooks, state, rendering, effects, and behavior tests. |
+| `refactoring/` | Behavior-preserving cleanup, staged changes, and characterization tests. |
+| `springboot/` | Spring Boot controller, service, repository, configuration, and actuator guidance. |
+| `sql/` | Relational schema, query, index, migration, and transaction guidance. |
+| `testing/` | Overall test strategy across unit, integration, contract, E2E, and regression tests. |
+| `typescript/` | TypeScript type modeling, runtime validation, and shared type guidance. |
+| `unit-tests/` | Fast isolated tests for pure logic, services, validators, reducers, and bug regressions. |
+
+## Loading Order
+
+When applying this role, load files in this order:
+
+1. `role.md` to establish behavior and constraints.
+2. `triggers.md` if the request type is ambiguous.
+3. `workflow.md` for the lifecycle stage.
+4. `skill-map.md` to select supporting skills.
+5. `checklists.md` for execution gates.
+6. Topic folders such as `api/`, `backend/`, `frontend/`, `database/`, `testing/`, or `logging/` when the task touches that area.
+7. `examples.md` when implementation style or test shape needs concrete reference.
+
+For project work, also load `context/engineering.md` and the relevant
+`projects/<project>/context.md` file when it exists.
+
+## Topic Folders
+
+Each topic folder follows the same mini-packet shape:
+
+- `README.md` explains scope, standards, and related folders.
+- `checklists.md` lists design, implementation, and verification gates.
+- `examples.md` provides starter examples or templates.
+
+Load only the topic packets that match the current task. For example, an
+authenticated API endpoint might load `api/`, `authentication/`,
+`authorization/`, `backend/`, `testing/`, and `logging/`; a React form change
+might load `frontend/`, `react/`, `typescript/`, and `frontend/testing/`.
+
+## Completion Standard
+
+A software-development task is complete only when:
+
+- The requested behavior works and edge cases are considered.
+- The change fits the existing architecture and local conventions.
+- Tests or verification steps cover the risk introduced by the change.
+- Security and privacy implications have been checked.
+- Observability is sufficient for operating the change in production.
+- Documentation or runbooks are updated when behavior, contracts, setup, or operations change.
+- The final response states what changed and what was verified.
+
+## Related Repository Areas
+
+- `skills/software-development/` for general engineering skills.
+- `skills/qa/` for test strategy and quality gates.
+- `skills/security/` for secure coding and privacy rules.
+- `skills/performance/` for latency, throughput, and measurement guidance.
+- `context/engineering.md` for shared engineering norms.
+- `context/communication.md` for stakeholder and review communication.

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

@@ -0,0 +1,365 @@
+# API Layer Reference Documentation
+
+The **API layer** (`src/<package>/api/`) is the public interface of the application. It exposes functionality to external clients such as web applications, mobile applications, and other services.
+
+All endpoints are:
+
+* Versioned under `/v1`
+* Protected using API key authentication
+* Validated against an OpenAPI 3.1 specification
+* Fully documented with Swagger / ReDoc
+
+---
+
+# Table of Contents
+
+* Package Layout
+* Running the API Locally
+* Generating the OpenAPI Specification
+* Example Requests
+* Testing Strategy
+* Adding a New Endpoint
+* Related Documentation
+
+---
+
+# Package Layout
+
+```text
+src/
+└── <package>/
+    └── api/
+        ├── v1/
+        │   ├── router.py
+        │   ├── endpoints/
+        │   │   ├── users.py
+        │   │   ├── generate.py
+        │   │   └── health.py
+        │   │
+        │   ├── schemas/
+        │   │   ├── user.py
+        │   │   └── generate.py
+        │   │
+        │   └── utils.py
+        │
+        ├── __init__.py
+        │
+        ├── docs/
+        │   └── openapi.yaml
+        │
+        └── tests/
+            ├── unit/
+            └── integration/
+```
+
+## Directory Overview
+
+| Directory    | Purpose                        |
+| ------------ | ------------------------------ |
+| `router.py`  | Registers all API routes       |
+| `endpoints/` | Route handlers                 |
+| `schemas/`   | Request/Response models        |
+| `utils.py`   | Shared API helpers             |
+| `docs/`      | OpenAPI specification          |
+| `tests/`     | API unit and integration tests |
+
+> **Guideline:** All public endpoints must be registered through the API router. Never expose internal functions directly.
+
+---
+
+# Running the API Locally
+
+## 1. Create a Virtual Environment
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
+
+---
+
+## 2. Install Dependencies
+
+```bash
+pip install --upgrade pip
+
+pip install -r requirements.txt
+
+pip install -r dev-requirements.txt
+```
+
+Development dependencies include:
+
+* FastAPI
+* Uvicorn
+* Pytest
+* HTTPX
+* Ruff
+* MyPy
+
+---
+
+## 3. Start the Development Server
+
+```bash
+uvicorn src.<package>.api.v1.main:app \
+    --reload \
+    --port 8000
+```
+
+---
+
+## Local URLs
+
+| Service    | URL                         |
+| ---------- | --------------------------- |
+| API        | http://localhost:8000       |
+| Swagger UI | http://localhost:8000/docs  |
+| ReDoc      | http://localhost:8000/redoc |
+
+---
+
+## Configure the API Key
+
+```bash
+export MYAPP_API_KEY=<your-secret>
+```
+
+Every request must include:
+
+```http
+X-Api-Key: <YOUR_API_KEY>
+```
+
+Missing or invalid keys return:
+
+```http
+401 Unauthorized
+```
+
+---
+
+# Generating the OpenAPI Specification
+
+The OpenAPI document lives at:
+
+```text
+api/docs/openapi.yaml
+```
+
+Regenerate the specification after API changes.
+
+```bash
+python scripts/generate_openapi.py
+```
+
+Commit the updated specification.
+
+```bash
+git add api/docs/openapi.yaml
+
+git commit -m "chore: update OpenAPI specification"
+```
+
+Validate the specification.
+
+```bash
+scripts/validate_openapi.sh
+```
+
+If adding a new endpoint:
+
+* Add the path definition.
+* Add request/response schemas.
+* Reference components.
+* Validate the specification before opening a PR.
+
+---
+
+# Example Requests
+
+## Create User
+
+### Request
+
+```bash
+curl -X POST http://localhost:8000/v1/users \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: $MYAPP_API_KEY" \
+  -d '{
+        "email":"test@example.com",
+        "first_name":"Test",
+        "last_name":"User"
+      }' | jq
+```
+
+---
+
+### Response
+
+```json
+{
+  "user_id": "u_9f3a2c7b-5e1d-4b8e-9c33-71d9c1e5b6f2",
+  "email": "test@example.com",
+  "full_name": "Test User",
+  "created_at": "2025-11-03T14:32:10Z",
+  "api_version": "v1"
+}
+```
+
+---
+
+## Generate Text
+
+```bash
+curl -X POST http://localhost:8000/v1/generate \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: $MYAPP_API_KEY" \
+  -d @examples/generate_request.json | jq
+```
+
+Additional request payload examples are available in:
+
+```text
+api/examples.md
+```
+
+---
+
+# Testing Strategy
+
+| Test Type   | Tool               | Command                                                                          | Purpose                            |
+| ----------- | ------------------ | -------------------------------------------------------------------------------- | ---------------------------------- |
+| Unit        | Pytest             | `pytest tests/unit`                                                              | Business logic and schemas         |
+| Integration | HTTPX / TestClient | `pytest tests/integration/api`                                                   | Complete request/response flow     |
+| Contract    | Schemathesis       | `schemathesis openapi --host http://localhost:8000 --spec api/docs/openapi.yaml` | OpenAPI compliance                 |
+| Performance | Locust             | `locust -f tests/performance/load_test.py`                                       | Latency and throughput             |
+| Security    | Bandit / Safety    | `bandit -r src`<br>`safety check -r requirements.txt`                            | Vulnerabilities and secret leakage |
+
+All test suites must pass before a Pull Request can be merged.
+
+---
+
+# Adding a New Endpoint
+
+## 1. Design
+
+Create:
+
+```text
+docs/design/<TICKET_ID>-<feature>.md
+```
+
+Define:
+
+* Business requirements
+* API contract
+* OpenAPI schema
+
+---
+
+## 2. Implement
+
+Add endpoint code under:
+
+```text
+src/<package>/api/v1/endpoints/
+```
+
+Add schemas under:
+
+```text
+src/<package>/api/v1/schemas/
+```
+
+---
+
+## 3. Validate
+
+Run:
+
+```bash
+schemathesis openapi \
+    --host http://localhost:8000 \
+    --spec api/docs/openapi.yaml
+```
+
+Fix any contract violations.
+
+---
+
+## 4. Test
+
+Create:
+
+* Unit tests
+* Integration tests
+* Error-path tests
+
+---
+
+## 5. Document
+
+Update:
+
+* OpenAPI specification
+* API examples
+* Runbooks
+* Design documentation
+
+---
+
+## 6. Review
+
+Open a Pull Request.
+
+Complete:
+
+```text
+roles/software-developer/api/checklist.md
+```
+
+---
+
+## 7. Deploy
+
+Follow the deployment workflow:
+
+```text
+Version Bump
+        ↓
+Docker Build
+        ↓
+Helm Deployment
+        ↓
+Canary Release
+        ↓
+Production
+```
+
+---
+
+# Related Documentation
+
+| Document                                     | Purpose                            |
+| -------------------------------------------- | ---------------------------------- |
+| `roles/software-developer/role.md`           | Software Developer role definition |
+| `skills/software-development/workflows.md`   | Development lifecycle              |
+| `roles/software-developer/api/checklist.md` | API development checklist          |
+| `roles/software-developer/skill-map.md`      | Skill loading and mappings         |
+| `skills/software-development/examples.md`    | End-to-end API examples            |
+| `ops/runbooks/`                              | Operational runbooks               |
+| `api/docs/openapi.yaml`                      | Complete OpenAPI specification     |
+
+---
+
+# Best Practices
+
+* Keep all endpoints versioned.
+* Validate all request payloads.
+* Return consistent error responses.
+* Keep OpenAPI documentation synchronized with code.
+* Write tests before opening a Pull Request.
+* Prefer backward-compatible API changes.
+* Never expose internal implementation details through public endpoints.
+* Follow semantic versioning for API changes.