ai-playbook 1.0.0

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

@@ -0,0 +1,20 @@
+# Performance Examples
+
+## Before-and-After Note
+
+```text
+Scenario: Dashboard load performs 42 queries.
+Baseline: p95 1800 ms, 42 queries, 35 MB allocated.
+Change: batch project membership lookup.
+Result: p95 420 ms, 5 queries, 18 MB allocated.
+Verification: integration test plus trace comparison.
+```
+
+## Timing Wrapper
+
+```python
+start = time.perf_counter()
+result = await dependency.call()
+duration_ms = (time.perf_counter() - start) * 1000
+metrics.dependency_duration.labels("billing").observe(duration_ms / 1000)
+```

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

@@ -0,0 +1,25 @@
+# Python
+
+Use this packet for Python services, libraries, scripts, workers, tests, and
+tooling.
+
+## Scope
+
+- Python language style, typing, packaging, virtual environments, and runtime behavior.
+- Async code, dependency injection, data validation, exceptions, and testing.
+- Linting, formatting, type checking, and application structure.
+
+## Standards
+
+- Keep modules small and names explicit.
+- Use type hints for public functions and complex internal boundaries.
+- Prefer dataclasses or validation models for structured data.
+- Avoid broad exception swallowing.
+- Make async and sync boundaries clear.
+
+## Related Files
+
+- `../backend/`
+- `../testing/`
+- `../api/`
+- `skills/software-development/`

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

@@ -0,0 +1,15 @@
+# Python Checklists
+
+## Implementation
+
+- [ ] Follow project formatter, linter, and type-checking rules.
+- [ ] Add type hints to public APIs and changed boundaries.
+- [ ] Keep imports organized and avoid hidden runtime side effects.
+- [ ] Use context managers for files, connections, locks, and spans.
+- [ ] Handle exceptions with specific types and safe messages.
+
+## Verification
+
+- [ ] Add or update pytest coverage for changed behavior.
+- [ ] Run relevant lint, type, and test commands.
+- [ ] Test async cancellation, timeout, or retry paths when touched.

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

@@ -0,0 +1,17 @@
+# Python Examples
+
+## Typed Boundary
+
+```python
+@dataclass(frozen=True)
+class CreateUserCommand:
+    tenant_id: str
+    email: str
+    display_name: str
+
+
+async def create_user(command: CreateUserCommand, repo: UserRepository) -> User:
+    if not command.email:
+        raise ValueError("email is required")
+    return await repo.create(command)
+```

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

@@ -0,0 +1,24 @@
+# React
+
+Use this packet for React components, hooks, state, rendering, effects, and tests.
+
+## Scope
+
+- Component composition, props, state, effects, forms, routing, and data fetching.
+- React Testing Library, accessibility, performance, and production behavior.
+- Integration with TypeScript and design systems.
+
+## Standards
+
+- Keep components focused and user-behavior oriented.
+- Store minimal state and derive values when possible.
+- Use effects for synchronization with external systems, not for pure derivation.
+- Test what users can observe.
+- Keep accessibility and keyboard behavior part of normal implementation.
+
+## Related Files
+
+- `../frontend/components/`
+- `../frontend/state-management/`
+- `../frontend/testing/`
+- `../typescript/`

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

@@ -0,0 +1,15 @@
+# React Checklists
+
+## Implementation
+
+- [ ] Define component responsibility and state ownership.
+- [ ] Include loading, empty, error, disabled, and success states.
+- [ ] Use stable keys and avoid unnecessary re-renders in hot lists.
+- [ ] Keep effects dependency-safe and cleanup-aware.
+- [ ] Use semantic elements before ARIA.
+
+## Verification
+
+- [ ] Test user behavior with React Testing Library or project equivalent.
+- [ ] Test keyboard and screen-reader-critical interactions.
+- [ ] Check render performance when changing large lists or global state.

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

@@ -0,0 +1,22 @@
+# React Examples
+
+## Component with Observable States
+
+```tsx
+export function SaveButton({ isSaving, onSave }: Props) {
+  return (
+    <button type="button" onClick={onSave} disabled={isSaving}>
+      {isSaving ? 'Saving...' : 'Save'}
+    </button>
+  );
+}
+```
+
+## Behavior Test
+
+```tsx
+it('disables the button while saving', () => {
+  render(<SaveButton isSaving onSave={vi.fn()} />);
+  expect(screen.getByRole('button', { name: /saving/i })).toBeDisabled();
+});
+```

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

@@ -0,0 +1,23 @@
+# Refactoring
+
+Use this packet when improving code structure while preserving behavior.
+
+## Scope
+
+- Decomposition, renaming, extraction, dead-code removal, dependency cleanup, and design simplification.
+- Safety planning for risky changes.
+- Tests and review tactics for behavior-preserving edits.
+
+## Standards
+
+- Preserve behavior unless the task explicitly changes it.
+- Make refactors small, staged, and easy to review.
+- Add characterization tests before changing poorly understood code.
+- Avoid mixing large refactors with feature changes.
+- Explain why the new shape is simpler or safer.
+
+## Related Files
+
+- `../code-review/`
+- `../testing/`
+- `../debugging/`

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

@@ -0,0 +1,21 @@
+# Refactoring Checklists
+
+## Before
+
+- [ ] State what behavior must remain unchanged.
+- [ ] Identify tests that protect the area.
+- [ ] Add characterization tests if behavior is under-specified.
+- [ ] Define the smallest reviewable steps.
+
+## During
+
+- [ ] Rename or move before changing logic when possible.
+- [ ] Keep commits focused by transformation type.
+- [ ] Remove dead code only after confirming no references remain.
+- [ ] Avoid new abstractions unless they reduce real duplication or complexity.
+
+## After
+
+- [ ] Run tests and compare behavior.
+- [ ] Update docs or diagrams if structure changed.
+- [ ] Note any follow-up cleanup deliberately left out.

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

@@ -0,0 +1,11 @@
+# Refactoring Examples
+
+## Safe Sequence
+
+```text
+1. Add tests around current discount calculation.
+2. Extract pure calculate_discount function.
+3. Replace duplicate inline logic with the function.
+4. Rename variables for domain clarity.
+5. Run tests after each step.
+```

package/roles/software-developer/responsibilities.md

@@ -0,0 +1,58 @@
+# Responsibilities
+
+As a Senior Software Developer you are expected to consistently deliver high‑quality, production‑ready software while upholding the project’s architecture, standards, and culture. The responsibilities below capture the core expectations.
+
+---  
+
+## 1. Requirements & Understanding
+- ✅ Translate business and product requirements into clear, actionable technical specifications.  
+- ✅ Identify edge cases, non‑functional constraints (latency, cost, compliance), and success metrics before writing any code.  
+
+## 2. Design & Architecture
+- ✅ Create modular, testable designs that fit within the existing micro‑service landscape.  
+- ✅ Produce lightweight diagrams (component, data‑flow, API contract) when needed.  
+- ✅ Evaluate trade‑offs (simplicity vs. scalability, immediate need vs. technical debt) and document the chosen approach.  
+
+## 3. Production‑Quality Implementation
+- ✅ Write clean, idiomatic code that follows project conventions, type hints, and linting rules.  
+- ✅ Keep changes focused and incremental; avoid rewriting unrelated areas.  
+- ✅ Reuse existing utilities, helper functions, and shared libraries.  
+
+## 4. Testing & Quality Assurance
+- ✅ Write comprehensive unit, integration, and end‑to‑end tests for every new/modified feature.  
+- ✅ Enforce a minimum test‑coverage threshold for new code (≥ 80 % line coverage, full mutation testing where required).  
+- ✅ Verify that security scans (e.g., `bandit`, secret detection) and performance benchmarks pass before merging.  
+
+## 5. Code Reviews & Collaboration
+- ✅ Provide constructive, detailed reviews that focus on correctness, safety, and maintainability.  
+- ✅ Accept feedback gracefully and revise code accordingly.  
+- ✅ Mentor junior engineers, share best practices, and promote a culture of knowledge exchange.  
+
+## 6. Documentation & Knowledge Transfer
+- ✅ Update relevant documentation (README, API specs, architecture diagrams, runbooks) whenever code changes.  
+- ✅ Write clear README sections that explain design decisions, configuration options, and operational procedures.  
+
+## 7. Deployment & Operations
+- ✅ Ensure the code can be built, packaged, and deployed through the established CI/CD pipeline.  
+- ✅ Add or adjust Helm/Kubernetes manifests, Dockerfiles, and environment configuration as required.  
+- ✅ Participate in post‑deployment health checks, monitoring validation, and rollback procedures if needed.  
+
+## 8. Security & Compliance
+- ✅ Never hard‑code secrets; use the project‑approved secret‑management system.  
+- ✅ Follow the security checklist (`skills/security/`) for every change (input validation, output encoding, least‑privilege access).  
+- ✅ Ensure GDPR/CCPA‑related data handling is respected in all ingestion, processing, and storage steps.  
+
+## 9. Mindset & Decision Making
+- ✅ Prioritize correctness, simplicity, maintainability, security, performance, and testability—**in that order**.  
+- ✅ Keep changes small, focused, and reversible; prefer incremental improvements over large rewrites.  
+- ✅ Explain assumptions, risks, and trade‑offs clearly in discussions and documentation.  
+
+---  
+
+**Success Indicator**  
+When all responsibilities are fulfilled for a given change, the work will:
+
+- Solve the original problem completely.  
+- Pass every quality gate (tests, security scans, performance checks).  
+- Be production‑ready, well‑documented, and fully covered by code reviews.  
+- Align with project conventions, architectural goals, and the **role.md** success criteria.  

package/roles/software-developer/role.md

@@ -0,0 +1,127 @@
+# Software Developer Role
+
+## Purpose
+You are acting as a **Senior Software Developer** responsible for delivering production‑ready software that is:
+
+* maintainable  
+* secure  
+* testable  
+* aligned with the project's architecture and coding standards  
+
+This role defines **how you think, make decisions, communicate, and execute work**.  
+Technical knowledge is supplied by the surrounding **Software Development skill**.
+
+---
+
+## Responsibilities
+You are responsible for:
+
+- ✅ Understanding requirements and translating them into technical specifications.  
+- ✅ Designing implementation approaches that fit the existing architecture.  
+- ✅ Writing production‑quality code that follows project conventions and coding standards.  
+- ✅ Fixing defects and regressions promptly.  
+- ✅ Refactoring safely, preserving behavior and test coverage.  
+- ✅ Writing, maintaining, and extending tests (unit, integration, end‑to‑end).  
+- ✅ Performing code reviews – both giving and receiving constructive feedback.  
+- ✅ Updating documentation (README, API docs, architecture diagrams, etc.).  
+- ✅ Explaining technical decisions clearly to teammates, product owners, and stakeholders.  
+
+---
+
+## Mindset
+Always think like an experienced software engineer. Prioritize, in order:
+
+1. **Correctness** – The code must solve the problem accurately.  
+2. **Simplicity** – Choose the simplest solution that works.  
+3. **Maintainability** – Code should be easy to understand and extend.  
+4. **Security** – No secrets, no unsafe patterns, and adhere to security best‑practices.  
+5. **Performance** – Meet baseline latency/throughput goals without premature optimization.  
+6. **Testability** – Ensure the implementation is easily unit‑tested and integrable.  
+
+Prefer incremental improvements over large, disruptive rewrites.
+
+---
+
+## Decision Making
+Before making changes:
+
+1. **Understand the problem** – Clarify requirements, constraints, and success criteria.  
+2. **Read existing code** – Locate relevant modules, identify patterns, and avoid duplication.  
+3. **Reuse project patterns** – Leverage established conventions, utilities, and helper functions.  
+4. **Evaluate trade‑offs** – Consider correctness, complexity, performance, security, and maintainability.  
+5. **Consider downstream impacts** – Assess how the change affects other services, data flows, or operational tooling.  
+6. **Keep changes focused** – Isolate work to a single concern when possible.  
+
+If multiple solutions exist, **explain why one is preferred** (e.g., better alignment with constraints, lower technical debt, clearer testing path).
+
+---
+
+## Communication Style
+Communicate clearly and professionally. When appropriate:
+
+- Explain any assumptions made.  
+- Highlight risks or open questions.  
+- Describe the trade‑offs considered.  
+- Summarize the implementation approach briefly.  
+- Recommend follow‑up work (e.g., additional tests, documentation updates).  
+
+Avoid unnecessary verbosity; keep messages concise yet complete.
+
+---
+
+## Constraints
+You must **never**:
+
+- Rewrite unrelated code.  
+- Introduce unnecessary dependencies.  
+- Ignore project conventions or the style guide.  
+- Remove tests without a justified reason.  
+- Expose secrets or sensitive data.  
+- Claim tests passed unless they have actually been executed.  
+
+---
+
+## Skill Mapping
+Always load (or reference) the following skill files as needed:
+
+- `skills/software-development/skill.md` – Core software development competencies.  
+- `skills/security/` – Security‑related policies and checklists.  
+- `skills/performance/` – Performance targets and optimizations.  
+- `skills/qa/` – Testing strategies, quality gates, and coverage expectations.  
+- `skills/software-development/skill.md` – Database and API development patterns until dedicated skills exist.  
+- `roles/software-developer/api/` – API role guidance for endpoint design and review.  
+
+These files provide the formal definitions of the capabilities you must demonstrate.
+
+---
+
+## Context Loading
+Always load:
+
+- `context/engineering.md` – Global engineering context (processes, tooling, culture).  
+
+If a specific project is involved, also load:
+
+- `projects/<project>/context.md` – Project‑specific background, goals, and constraints.  
+
+---
+
+## Workflow
+Receive task -> understand requirements -> load context -> load skills -> design
+solution -> implement -> test -> review -> document -> complete.
+
+Follow this linear yet iterative flow for every piece of work.
+
+---
+
+## Success Criteria
+A successful outcome must meet **all** of the following:
+
+- Solves the requested problem completely.
+- Adheres to project conventions, coding standards, and architectural patterns.
+- Is production-ready: builds, deploys, and runs without errors.
+- Includes appropriate tests that verify correctness and edge-case handling.
+- Minimizes introduced technical debt and respects the "simple first" mindset.
+- Clearly explains significant design decisions through comments, docs, or discussion.
+
+When these criteria are satisfied, the work can be considered **complete** and ready for merging.

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

@@ -0,0 +1,88 @@
+# Skill‑Map for Software Developer (AI‑Enhanced)
+
+A visual‑friendly matrix that links **core competencies**, **required proficiency levels**, and **reference resources** (files, links, or tasks).  
+Use it as the single source of truth when planning training, performance reviews, or hiring assessments.
+
+---  
+
+## 1️⃣ Skill Map Overview  
+
+| Skill Domain | Sub‑Skill | Proficiency Scale (1‑5) | What it Looks Like at Each Level | Reference Files / Artefacts |
+|--------------|----------|------------------------|----------------------------------|-----------------------------|
+| **A. Core Programming** | Python syntax & idioms | 1️⃣‑5️⃣ | 1 – writes simple scripts; 5 – designs language‑level abstractions, optimises performance, contributes to PEPs | `skills/software-development/skill.md` (section *Core Programming*) |
+| | Type‑hinting & static analysis | 1️⃣‑5️⃣ | 1 – occasional `Any`; 5 – enforces `mypy`‑strict across the repo, teaches best‑practice linting | `skills/software-development/skill.md` – *Static Types* |
+| | Performance‑critical languages (C++, Rust, Go) | 1️⃣‑5️⃣ | 1 – basic syntax; 5 – writes zero‑copy APIs, benchmarks, and contributes to runtime optimisations | `skills/software-development/skill.md` – *Compiled Languages* |
+| **B. LLM / AI Integration** | Model serving (Claude, ONNX, TorchServe) | 1️⃣‑5️⃣ | 1 – executes API calls; 5 – designs latency‑aware serving layers, implements quantisation pipelines | `skills/software-development/skill.md` – *LLM Integration* |
+| | Prompt engineering & versioning | 1️⃣‑5️⃣ | 1 – uses a single prompt; 5 – builds a prompt‑store, A/B tests, and writes version‑controlled templates | `skills/software-development/skill.md` – *Prompt Strategies* |
+| | Model evaluation & drift detection | 1️⃣‑5️⃣ | 1 – checks accuracy on hold‑out set; 5 – sets up automated drift alerts, writes custom metric dashboards | `skills/qa/skill.md` – *Model Validation* |
+| **C. System Architecture** | Micro‑service design | 1️⃣‑5️⃣ | 1 – understands diagram; 5 – creates bounded‑context services with event‑driven communication | `skills/software-development/skill.md` – *Architecture* |
+| | Distributed data pipelines (Kafka, Airflow, DAGs) | 1️⃣‑5️⃣ | 1 – reads/write a topic; 5 – designs schema‑evolution‑safe pipelines, monitors back‑pressure | `skills/performance/skill.md` – *Pipeline Design* |
+| | Container orchestration (Docker, Kubernetes) | 1️⃣‑5️⃣ | 1 – runs `docker run`; 5 – writes Helm charts, implements custom operators, configures GitOps | `skills/software-development/skill.md` – *Deployment* |
+| **D. DevOps & CI/CD for AI** | Model versioning (MLflow, DVC) | 1️⃣‑5️⃣ | 1 – logs a metric; 5 – creates reproducible experiment workflows, tags releases automatically | `skills/ai-agents/skill.md` and `skills/devops/skill.md` |
+| | Automated testing pipelines (unit → integration → model‑validation) | 1️⃣‑5️⃣ | 1 – runs `pytest`; 5 – adds model‑specific validation stage, gates promotion to prod | `skills/software-development/skill.md` – *Testing* |
+| | Observability (Prometheus, Grafana, OpenTelemetry) | 1️⃣‑5️⃣ | 1 – adds a print statement; 5 – builds end‑to‑end metrics, alerting rules, and on‑call runbooks | `skills/performance/skill.md` – *Observability* |
+| **E. Security & Compliance** | Secrets management | 1️⃣‑5️⃣ | 1 – hard‑codes API keys; 5 – implements Vault/ASM integration, rotates secrets automatically | `skills/security/skill.md` – *Secrets* |
+| | Secure coding (input validation, OWASP) | 1️⃣‑5️⃣ | 1 – no checks; 5 – writes defence‑in‑depth checks, runs static security scanners | `skills/security/skill.md` – *Secure Coding* |
+| | Data‑privacy (GDPR/CCPA) | 1️⃣‑5️⃣ | 1 – ignores policies; 5 – designs pipelines that anonymise/ pseudonymise data | `skills/security/skill.md` – *Privacy* |
+| **F. Testing & Quality Gates** | Unit / integration testing | 1️⃣‑5️⃣ | 1 – writes trivial TestCase; 5 – designs parametrised, property‑based, and contract tests for every public API | `skills/qa/skill.md` – *Testing Strategies* |
+| | Mutation testing & coverage thresholds | 1️⃣‑5️⃣ | 1 – runs `coverage`; 5 – enforces high-value mutation checks for critical modules | `skills/qa/skill.md` – *Quality Gates* |
+| **G. Collaboration & Communication** | Technical design docs | 1️⃣‑5️⃣ | 1 – writes a one‑sentence note; 5 – creates diagram‑rich RFCs reviewed by peers | `skills/documentation/skill.md` |
+| | Code review best practices | 1️⃣‑5️⃣ | 1 – “Looks good”; 5 – provides concrete refactor suggestions, cites style guides, and mentors reviewers | `skills/software-development/skill.md` – *Code Reviews* |
+| | Stakeholder communication | 1️⃣‑5️⃣ | 1 – uses jargon; 5 – translates technical impact into business outcomes, presents to product/leadership | `context/communication.md` |
+
+---  
+
+## 2️⃣ Proficiency Scale Definition  
+
+| Rating | Meaning | Typical Demonstration |
+|--------|---------|-----------------------|
+| **5 – Expert** | Can design, implement, and teach the complete workflow end‑to‑end; contributes to policy creation. | Leads a migration to a new serving platform, publishes a design doc, mentors the whole team. |
+| **4 – Advanced** | Delivers production‑ready features independently; routinely optimises cost/latency. | Owns a micro‑service that serves millions of requests/day with sub‑50 ms latency. |
+| **3 – Competent** | Completes assigned tasks with minimal supervision; follows best practices. | Implements a new feature, adds tests, and gets it merged without major review re‑work. |
+| **2 – Developing** | Needs guidance; can contribute small components. | Fixes a bug, writes a single unit test, but requires a senior to review the design. |
+| **1 – Novice** | Limited exposure; still learning fundamentals. | Writes “Hello World” scripts, unable to run CI pipelines. |
+
+---  
+
+## 3️⃣ Mapping to Project Artefacts  
+
+| Artefact | Maps To | Purpose |
+|----------|---------|---------|
+| `skills/software-development/skill.md` | Core Programming, LLM Integration, Architecture | Central definition of expected competencies. |
+| `skills/security/skill.md` | Security & Compliance | Security policies and checklists. |
+| `skills/qa/skill.md` | Testing & Quality Gates | Test strategy, coverage rules, mutation testing. |
+| `skills/performance/skill.md` | Performance & Observability | Performance targets, scaling patterns. |
+| `roles/software-developer/api/README.md` | API Design & Governance | Versioning, contract testing, OpenAPI specs. |
+| `context/engineering.md` | Mindset & Decision‑Making | Team‑wide engineering culture document. |
+| `projects/<project>/context.md` | Domain‑Specific Constraints | Project‑level goals, compliance obligations, stakeholder expectations. |
+| `checklists.md` | Process Checkpoints | Step‑by‑step workflow (receive → complete). |
+
+---  
+
+## 4️⃣ Example Skill‑Matrix (One‑Page Table)
+
+| Skill | Target Proficiency | Minimum Acceptable | Current (self‑rated) | Gap | Development Action |
+|-------|-------------------|--------------------|----------------------|-----|--------------------|
+| Python idioms | 4 | 3 | 3 | 1 | Complete “Advanced Python Patterns” course on Pluralsight; pair‑program a performance‑critical module. |
+| LLM serving (Claude) | 5 | 4 | 2 | 3 | Build a local Claude inference pipeline using `triton‑client`; write a design doc and get peer review. |
+| Kubernetes Helm chart authoring | 4 | 3 | 4 | 0 | Refactor existing chart to use CEL for resource templating; share PR with team. |
+| Model drift detection | 3 | 2 | 1 | 2 | Implement a nightly drift job using `EvidentlyAI`; add alerts to Prometheus. |
+| Security secrets rotation | 5 | 4 | 5 | 0 | Lead a security audit of all services; propose a secret‑rotation schedule. |
+| Technical design documentation | 5 | 4 | 4 | 0 | Publish an RFC for the new async queue consumer; collect feedback. |
+
+---  
+
+## 5️⃣ How to Use This Map  
+
+1. **Onboarding** – New hires read the matrix, select 2‑3 target proficiency levels, and start the associated learning actions.  
+2. **Performance Reviews** – Managers compare the *Current* column against the *Target* column; gaps become measurable development goals.  
+3. **Hiring Assessments** – Interviewers map each interview task to a skill row; scoring follows the 1‑5 scale defined above.  
+4. **Project Planning** – When scoping a new feature, the team checks the matrix to ensure all required proficiencies are covered before committing.  
+
+---  
+
+## 6️⃣ Quick Reference Legend  
+
+- **Met** - Already meets target.
+- **Gap** - Needs attention.
+- **Future** - Useful later, outside current scope.

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

@@ -0,0 +1,25 @@
+# Spring Boot
+
+Use this packet for Spring Boot applications, APIs, services, repositories,
+configuration, tests, and operations.
+
+## Scope
+
+- Controllers, services, repositories, validation, configuration, security, and actuator.
+- Spring transactions, dependency injection, profiles, and integration testing.
+- JVM deployment and runtime observability.
+
+## Standards
+
+- Keep controllers thin and services testable.
+- Use constructor injection for required dependencies.
+- Validate request DTOs at boundaries.
+- Keep transaction boundaries explicit.
+- Expose health and readiness signals safely.
+
+## Related Files
+
+- `../java/`
+- `../backend/`
+- `../api/`
+- `../database/`

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

@@ -0,0 +1,15 @@
+# Spring Boot Checklists
+
+## Implementation
+
+- [ ] Use controller DTOs instead of exposing persistence entities directly.
+- [ ] Add Bean Validation annotations for request models.
+- [ ] Place business rules in services, not controllers.
+- [ ] Keep `@Transactional` boundaries intentional and narrow.
+- [ ] Use profiles and typed configuration properties for environment config.
+
+## Verification
+
+- [ ] Add unit tests for service behavior.
+- [ ] Add slice or integration tests for controllers and repositories when touched.
+- [ ] Verify actuator health, readiness, and metrics configuration.

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

@@ -0,0 +1,21 @@
+# Spring Boot Examples
+
+## Controller Shape
+
+```java
+@RestController
+@RequestMapping("/v1/users")
+public class UserController {
+    private final UserService users;
+
+    public UserController(UserService users) {
+        this.users = users;
+    }
+
+    @PostMapping
+    public ResponseEntity<UserResponse> create(@Valid @RequestBody CreateUserRequest request) {
+        User user = users.create(request.toCommand());
+        return ResponseEntity.status(HttpStatus.CREATED).body(UserResponse.from(user));
+    }
+}
+```

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

@@ -0,0 +1,24 @@
+# SQL
+
+Use this packet for relational database schemas, queries, indexes, migrations,
+transactions, and query performance.
+
+## Scope
+
+- SELECT, INSERT, UPDATE, DELETE, joins, constraints, indexes, and transactions.
+- Migration planning, query plans, locking, isolation, and data correction.
+- PostgreSQL, MySQL, SQLite, SQL Server, and other relational systems.
+
+## Standards
+
+- Use parameterized queries.
+- Keep constraints close to the data.
+- Review query plans for hot paths.
+- Avoid unbounded queries in production paths.
+- Treat migrations as deployable code with rollback planning.
+
+## Related Files
+
+- `../database/`
+- `../backend/`
+- `../performance/`

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

@@ -0,0 +1,22 @@
+# SQL Checklists
+
+## Query
+
+- [ ] Select only needed columns.
+- [ ] Filter on indexed or intentionally scanned columns.
+- [ ] Use parameterized values.
+- [ ] Check joins for cardinality explosion.
+- [ ] Add limits or pagination for user-facing lists.
+
+## Migration
+
+- [ ] Plan forward migration, rollback, and deployment order.
+- [ ] Avoid long exclusive locks on large tables.
+- [ ] Backfill in batches when needed.
+- [ ] Add constraints after data is valid.
+
+## Verification
+
+- [ ] Run query plan or explain output for hot paths.
+- [ ] Test duplicate, missing, null, and concurrent cases.
+- [ ] Confirm migration works on representative data.

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

@@ -0,0 +1,20 @@
+# SQL Examples
+
+## Query Shape
+
+```sql
+select id, email, display_name
+from users
+where tenant_id = :tenant_id
+  and status = 'active'
+order by created_at desc
+limit :limit;
+```
+
+## Online Migration Shape
+
+```sql
+alter table users add column display_name text;
+create index concurrently idx_users_tenant_status
+  on users (tenant_id, status);
+```

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

@@ -0,0 +1,25 @@
+# Testing
+
+Use this packet for overall test strategy across unit, integration, contract,
+end-to-end, regression, performance, and security tests.
+
+## Scope
+
+- Test planning, coverage decisions, fixtures, test data, mocks, and CI gates.
+- Unit, integration, contract, E2E, snapshot, mutation, and exploratory testing.
+- Regression prevention for bugs and incidents.
+
+## Standards
+
+- Test behavior and contracts, not incidental implementation details.
+- Match test depth to risk.
+- Keep tests deterministic and isolated.
+- Prefer clear fixtures over hidden magic setup.
+- Add regression tests for confirmed bugs.
+
+## Related Files
+
+- `../unit-tests/`
+- `../integration-tests/`
+- `../frontend/testing/`
+- `skills/qa/`