ai-playbook 1.0.0

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

@@ -0,0 +1,21 @@
+# Testing Checklists
+
+## Plan
+
+- [ ] Identify risk: logic, integration, data, security, performance, or UI behavior.
+- [ ] Choose appropriate test type and scope.
+- [ ] Define fixtures, mocks, fakes, and cleanup strategy.
+- [ ] Include negative and edge cases.
+
+## Implementation
+
+- [ ] Use descriptive test names.
+- [ ] Keep arrange, act, assert steps clear.
+- [ ] Avoid dependence on test order, wall-clock time, or shared mutable state.
+- [ ] Test public behavior rather than private implementation when possible.
+
+## Verification
+
+- [ ] Run targeted tests and relevant broader suite.
+- [ ] Confirm failures are understandable.
+- [ ] Remove or quarantine flaky tests only with a tracked follow-up.

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

@@ -0,0 +1,19 @@
+# Testing Examples
+
+## Test Name Shape
+
+```python
+def test_create_user_rejects_duplicate_email_within_tenant():
+    ...
+```
+
+## Arrange Act Assert
+
+```python
+def test_total_includes_tax():
+    cart = Cart(items=[Item(price=100)], tax_rate=0.08)
+
+    total = cart.total()
+
+    assert total == 108
+```

package/roles/software-developer/triggers.md

@@ -0,0 +1,550 @@
+# Triggers.md
+## Event‑Driven Triggers for the End‑to‑End Development Lifecycle  
+
+This document enumerates every **trigger** that should cause an automatic or semi‑automatic action in the **Software‑Developer** workflow described by `role.md`, `checklists.md`, `skill-map.md`, and `responsibilities.md`.  
+Each trigger includes:
+
+* **Name** – a short identifier.  
+* **Source** – where the event originates (code push, schedule, external system, etc.).  
+* **Condition(s)** – the exact criteria that must be met for the trigger to fire.  
+* **Resulting Action(s)** – what the system shall do when the condition is satisfied (e.g., start a CI job, post a Slack message, run a script).  
+* **Configuration Hint** – a minimal example (YAML, CLI command, or JSON snippet) to help you wire the trigger in your tooling (GitHub Actions, Jenkins, GitLab CI, Argo Events, etc.).
+
+---  
+
+## 1️⃣ Triggers Overview  
+
+| # | Trigger | Typical Source | When It Fires | Primary Business Value |
+|---|---------|----------------|---------------|------------------------|
+| 1 | **Task‑Received** | Issue tracker (Jira, GitHub Issues, Asana) – new ticket assigned | Immediately after assignment | Notifies assignee, creates work‑item in the local sprint board, loads context. |
+| 2 | **Branch‑Created** | Git push / PR creation | New branch pushed to `remotes/origin/<branch>` | Starts a *feature‑branch* lint/CI pipeline, creates a preview environment. |
+| 3 | **Pull‑Request‑Opened / Updated** | Pull‑request event | PR opened or any subsequent push to the source branch | Begins review process, runs CI, posts status back to GitHub. |
+| 4 | **CI‑Pipeline‑Success** | CI system (GitHub Actions, Jenkins, GitLab CI) | All job stages (`lint`, `test`, `security-scan`, `build`) finish with **pass** | Allows merge, triggers deployment gate, notifies reviewers. |
+| 5 | **CI‑Pipeline‑Failure** | Same as #4 | Any stage returns a **failed** or **cancelled** status | Stops merge, opens a ticket for investigation, triggers alert. |
+| 6 | **Test‑Coverage‑Threshold‑Met** | Coverage tool (`coverage.py`, `nyc`, `gcov`) | Coverage of new code ≥ configured % (e.g., 80 % line, 70 % branch) | Unlocks merge, encourages quality compliance. |
+| 7 | **Security‑Scan‑Failure** | Static analysis/secret‑scan tools (`bandit`, `safety`, `git‑secret‑detect`) | Any finding severity ≥ **high** | Blocks merge, opens a security ticket, notifies security team. |
+| 8 | **Performance‑Benchmark‑Regression** | Benchmark suite (e.g., `locust`, `k6`, custom script) | Latency or throughput degrades beyond a defined SLA | Pauses promotion to production, triggers a rollback, notifies performance team. |
+| 9 | **Canary‑Deployment‑Completed** | Argo Rollouts / Flagger / Service Mesh | Canary traffic reaches target % and all health checks pass | Automatically promotes to full rollout or rolls back. |
+|10| **Post‑Deploy‑Health‑Check‑Pass** | Synthetic health‑check (HTTP `/healthz`, Prometheus alert silence) | All alerts cleared for **X** minutes after deployment | Clears release gate, updates status in issue tracker. |
+|11| **Scheduled‑Maintenance‑Window** | Calendar / cron job | At predefined times (e.g., nightly 02:00 UTC) | Executes migration scripts, dependency upgrades, or nightly build cleanup. |
+|12| **Version‑Release‑Tag‑Created** | Git tag push (`vX.Y.Z`) | A new release tag is pushed to `refs/tags/` | Triggers publishing to artifact repository, Docker image push, Helm chart bump. |
+|13| **External‑Webhook‑Received** | Third‑party system (payment gateway, analytics service) | Webhook payload meets verification criteria | Executes a dedicated handler, possibly updating a saga or starting a compensation flow. |
+|14| **SLA‑Violation‑Alert** | Monitoring platform (Prometheus, CloudWatch) | Any SLA (latency > 200 ms, error rate > 1 %) remains active for more than **N** minutes | Triggers on‑call escalation, auto‑remediation script, and incident ticket creation. |
+
+---  
+
+# Trigger Workflows
+
+This document defines the standard trigger events, conditions, and automated actions used by the Software Development role.
+
+---
+
+# 2.1 Task Received
+
+**Source**
+
+* Jira Issue
+* GitHub Issue
+* Azure DevOps Work Item
+* Linear Issue
+
+**Condition**
+
+* Issue created
+* Issue assigned
+* Status changes to **In Progress**
+
+**Actions**
+
+* Populate local checkout of the repository.
+
+```bash
+git fetch
+git checkout <branch>
+```
+
+* Load project context.
+
+```text
+context/engineering.md
+projects/<project>/context.md
+```
+
+* Create a temporary working document.
+
+```text
+tmp/<ticket_id>.md
+```
+
+* Initialize the document with the standard developer checklist.
+
+See:
+
+```text
+checklists.md
+```
+
+---
+
+## GitHub Actions Example
+
+```yaml
+on:
+  issues:
+    types:
+      - opened
+      - assigned
+
+jobs:
+  load-context:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Echo ticket ID
+        run: echo "Processing ${{ github.event.issue.number }}"
+```
+
+---
+
+# 2.2 Branch Created
+
+**Source**
+
+Git Push
+
+```text
+refs/heads/*
+```
+
+**Condition**
+
+Branch name matches:
+
+```text
+feature/*
+bugfix/*
+```
+
+**Actions**
+
+* Run Ruff
+* Run MyPy
+* Run Unit Tests
+* Create Preview Environment
+
+Example providers:
+
+* Fly.io
+* Heroku Review Apps
+* Render Preview
+* Vercel Preview
+
+---
+
+## GitLab CI Example
+
+```yaml
+branch-check:
+  stage: test
+
+  rules:
+    - if: $CI_COMMIT_BRANCH =~ /^feature\//
+
+  script:
+    - poetry install
+    - poetry run ruff check .
+    - poetry run mypy .
+    - poetry run pytest -q
+```
+
+---
+
+# 2.3 Pull Request Opened / Updated
+
+**Source**
+
+GitHub Pull Request
+
+**Condition**
+
+Target branch:
+
+```text
+main
+```
+
+or another protected branch.
+
+**Actions**
+
+* Post the standard PR checklist.
+
+```text
+- [ ] Load Context
+- [ ] Tests Added
+- [ ] Documentation Updated
+```
+
+* Notify Slack.
+
+---
+
+## Slack Payload
+
+```json
+{
+  "text": ":construction: PR *#${{ github.event.number }}* opened by <@${{ github.event.pull_request.user.id }}>.\n_Triggers: Task-Received, CI-Pipeline._"
+}
+```
+
+---
+
+# 2.4 CI Pipeline Success / Failure
+
+**Source**
+
+Workflow Run
+
+**Conditions**
+
+### Success
+
+```text
+result == success
+```
+
+**Actions**
+
+* Enable Merge
+* Trigger Canary Deployment
+
+---
+
+### Failure
+
+```text
+result == failure
+```
+
+**Actions**
+
+* Create CI Failure issue
+* Assign issue to author
+* Notify
+
+```text
+#ci-failures
+```
+
+---
+
+# 2.5 Test Coverage Threshold Met
+
+**Condition**
+
+```text
+Line Coverage >= 80%
+
+Branch Coverage >= 70%
+```
+
+For modified files only.
+
+---
+
+## Success
+
+* Allow Merge
+* Execute
+
+```text
+/merge
+```
+
+---
+
+## Failure
+
+Comment on the PR with:
+
+* Line Coverage
+* Branch Coverage
+* Coverage Report URL
+
+---
+
+# 2.6 Performance Benchmark Regression
+
+**Trigger**
+
+Nightly scheduled benchmark
+
+**Condition**
+
+```text
+Current Latency > 1.2 × Baseline
+```
+
+Baseline stored in:
+
+```text
+benchmark-baseline.yaml
+```
+
+---
+
+## Actions
+
+* Block Merge
+
+```text
+/hold
+```
+
+* Create Performance Regression incident
+* Optionally rollback using Argo Rollouts
+
+---
+
+# 2.7 Canary Deployment Completed
+
+**Source**
+
+Argo Rollouts
+
+**Condition**
+
+Traffic reaches:
+
+```yaml
+steps:
+  - setWeight: 50
+  - setWeight: 100
+```
+
+Prometheus alerts are clear.
+
+---
+
+## Actions
+
+* Promote deployment to Production
+* Notify
+
+```text
+#releases
+```
+
+---
+
+# 2.8 Post Deployment Health Check
+
+**Source**
+
+Health Endpoint
+
+```text
+/healthz
+```
+
+Prometheus
+
+```text
+up{job="myapp"}
+```
+
+**Condition**
+
+Healthy for:
+
+```text
+5 consecutive minutes
+```
+
+---
+
+## Actions
+
+* Update Jira
+
+```text
+In Progress → Done
+```
+
+* Run Documentation Update
+* Execute deployment checklist
+
+---
+
+# 3. Platform Configuration
+
+| Platform        | Configuration             |
+| --------------- | ------------------------- |
+| GitHub Actions  | `.github/workflows/*.yml` |
+| GitLab CI       | `.gitlab-ci.yml`          |
+| Jenkins         | `Jenkinsfile`             |
+| Argo Events     | `EventSource`             |
+| Prometheus      | `alertmanager.yml`        |
+| Jira Automation | Project Automation Rules  |
+
+---
+
+## GitHub Actions
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+
+  pull_request:
+    types:
+      - opened
+      - synchronize
+```
+
+---
+
+## GitLab CI
+
+```yaml
+ci:
+  trigger:
+    - job: build
+      when: on_success
+```
+
+---
+
+## Jenkins
+
+```groovy
+pipeline {
+    triggers {
+        pollSCM('H/5 * * * *')
+    }
+}
+```
+
+---
+
+## Argo Events
+
+```yaml
+apiVersion: argo.events.k8s.io/v1alpha1
+kind: EventSource
+
+metadata:
+  name: ci-success
+
+spec:
+  source:
+    http:
+      path: /status
+      method: POST
+```
+
+---
+
+## Prometheus Alertmanager
+
+```yaml
+receivers:
+  - name: slack-notifications
+
+    slack_configs:
+      - api_url: https://hooks.slack.com/services/...
+        channel: "#ops"
+```
+
+---
+
+## Jira Automation
+
+```text
+When Issue Created
+
+↓
+
+Transition
+
+↓
+
+In Progress
+
+↓
+
+Attach Checklist
+```
+
+---
+
+# 4. Best Practices for New Triggers
+
+Before introducing a new trigger:
+
+* Document the trigger source.
+* Document all trigger conditions.
+* Keep trigger configuration under version control.
+* Add automated tests for the trigger.
+* Send human-readable notifications.
+* Ensure idempotency.
+* Log structured event metadata.
+* Document rollback procedures.
+* Update related SOPs.
+* Update responsibilities and checklists.
+
+---
+
+# 5. End-to-End Trigger Flow
+
+```text
+Task Received
+      │
+      ▼
+Issue Created
+      │
+      ▼
+Developer Assigned
+      │
+      ▼
+Branch Created
+      │
+      ▼
+Preview Environment
+      │
+      ▼
+Pull Request Opened
+      │
+      ▼
+CI Pipeline
+      │
+      ▼
+Coverage Check
+      │
+      ▼
+Merge Approved
+      │
+      ▼
+Merge to Main
+      │
+      ▼
+Canary Deployment
+      │
+      ▼
+Production Deployment
+      │
+      ▼
+Health Checks
+      │
+      ▼
+Jira Updated
+      │
+      ▼
+Documentation Updated
+      │
+      ▼
+Release Completed
+```

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

@@ -0,0 +1,25 @@
+# TypeScript
+
+Use this packet for TypeScript application code, type design, runtime validation,
+frontend and Node.js projects.
+
+## Scope
+
+- Type modeling, generics, narrowing, discriminated unions, module boundaries, and build config.
+- Runtime validation for external data.
+- React, Node.js, and shared package types.
+
+## Standards
+
+- Model domain states explicitly.
+- Avoid `any` unless isolated and justified.
+- Use `unknown` plus validation for external inputs.
+- Keep exported types stable and documented.
+- Let types prevent impossible states where practical.
+
+## Related Files
+
+- `../javascript/`
+- `../react/`
+- `../node/`
+- `../frontend/code-quality/`

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

@@ -0,0 +1,15 @@
+# TypeScript Checklists
+
+## Implementation
+
+- [ ] Avoid new unbounded `any` in changed code.
+- [ ] Validate external data before casting or trusting it.
+- [ ] Use discriminated unions for variant states.
+- [ ] Keep exported types compatible with consumers.
+- [ ] Ensure tsconfig and lint rules remain satisfied.
+
+## Verification
+
+- [ ] Run type checking.
+- [ ] Add tests for runtime behavior, not just type satisfaction.
+- [ ] Verify generated or shared types are updated when contracts change.

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

@@ -0,0 +1,18 @@
+# TypeScript Examples
+
+## Discriminated Union
+
+```typescript
+type LoadState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; message: string };
+
+function renderUser(state: LoadState<User>) {
+  if (state.status === 'success') {
+    return state.data.displayName;
+  }
+  return state.status;
+}
+```

package/roles/software-developer/unit-tests/README.md

@@ -0,0 +1,24 @@
+# Unit Tests
+
+Use this packet for fast, isolated tests of pure functions, domain logic,
+validators, serializers, reducers, hooks, and small services.
+
+## Scope
+
+- Unit test structure, fixtures, assertions, mocks, and edge cases.
+- Characterization tests before refactoring.
+- Regression tests for isolated bug fixes.
+
+## Standards
+
+- Keep unit tests fast and deterministic.
+- Test observable behavior and meaningful edge cases.
+- Use mocks only at clear boundaries.
+- Avoid duplicating implementation logic in assertions.
+- Keep test names specific.
+
+## Related Files
+
+- `../testing/`
+- `../integration-tests/`
+- `../refactoring/`

package/roles/software-developer/unit-tests/checklists.md

@@ -0,0 +1,19 @@
+# Unit Test Checklists
+
+## Design
+
+- [ ] Identify the unit and its observable behavior.
+- [ ] List happy path, edge cases, and failure cases.
+- [ ] Decide which collaborators should be fakes, mocks, or real simple values.
+
+## Implementation
+
+- [ ] Keep setup minimal and explicit.
+- [ ] Use descriptive assertions.
+- [ ] Avoid testing private implementation details unless characterizing legacy behavior.
+- [ ] Keep tests independent and order-insensitive.
+
+## Verification
+
+- [ ] Run the test alone and with nearby tests.
+- [ ] Confirm failure messages point to the broken behavior.

package/roles/software-developer/unit-tests/examples.md

@@ -0,0 +1,22 @@
+# Unit Test Examples
+
+## Pure Function
+
+```typescript
+it('returns free shipping for orders above the threshold', () => {
+  const result = calculateShipping({ subtotal: 150, destination: 'US' });
+
+  expect(result.cost).toBe(0);
+  expect(result.reason).toBe('threshold_met');
+});
+```
+
+## Python Domain Rule
+
+```python
+def test_invoice_cannot_be_captured_twice():
+    invoice = Invoice(status="captured")
+
+    with pytest.raises(InvalidState):
+        invoice.capture()
+```