Add agent skills

.agents/skills/deploy-aws/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: deploy-aws
+description: Synthesizes, diffs, and deploys CDK Lambda stacks to AWS cloud environments using mise and CDK CLI. Use whenever the user asks to deploy, diff, or release a Lambda stack to AWS.
+category: coding
+tags: [aws, cdk, deploy, cloud, lambda, cur8d]
+---
+
+# Deploy cur8d Lambda Stacks to AWS
+
+This skill guides you through deploying AWS CDK Lambda stacks to a live AWS cloud environment adhering to cur8d quality and safety gates.
+
+## Prerequisites
+
+- AWS CLI configured with active credentials (`aws sts get-caller-identity` succeeds)
+- `mise` installed
+- Docker installed (required for CDK bundling and container image lambdas)
+
+## Workflow
+
+### 1. Verify Active AWS Identity & Target Environment
+Verify credentials and current account/region:
+
+```bash
+aws sts get-caller-identity
+```
+
+Ensure `AWS_REGION` or `AWS_DEFAULT_REGION` is explicitly configured.
+
+### 2. Pre-Flight Verification
+Run all tests and linters before executing any cloud deployment:
+
+```bash
+mise run verify
+```
+
+Fix any linting or test regressions before proceeding.
+
+### 3. Inspect CDK Infrastructure Changes (Diff)
+Generate a diff against the currently deployed cloud stack:
+
+```bash
+mise run diff <stack_name>
+```
+
+Carefully inspect:
+- Resources being added, updated, or destroyed (look out for accidental deletions of stateful resources like DynamoDB tables or S3 buckets).
+- IAM permission changes and policies.
+
+### 4. Deploy the Stack
+Deploy the stack to AWS:
+
+```bash
+mise run deploy <stack_name>
+```
+
+Monitor the deployment progress in the terminal output. Upon success, CDK outputs (API Gateway endpoints, ARN outputs) will be printed.
+
+### 5. Post-Deployment Verification
+- Test the deployed Lambda or API Gateway endpoint using `curl` or AWS CLI.
+- Check CloudWatch Logs for recent invocations:
+  ```bash
+  aws logs tail /aws/lambda/<function_name> --since 5m --follow
+  ```
+
+### 6. Teardown / Destruction (If Requested)
+To tear down the deployed stack:
+
+```bash
+mise run destroy <stack_name>
+```
+
+## Boundaries
+
+✅ **Always do:**
+- Always run `aws sts get-caller-identity` to confirm the target account before deploying.
+- Always run `mise run verify` and `mise run diff <stack_name>` prior to deployment.
+- Always capture and report cloud deployment outputs (e.g., API Gateway URLs) back to the user.
+
+🚫 **Never do:**
+- Never run deployment if `mise run verify` fails.
+- Never destroy production stacks without explicit user confirmation.

.agents/skills/init-project/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: init-project
+description: Initializes and customizes a new AWS Lambda service repository from the cur8d/lambda template. Use whenever the user asks to initialize, bootstrap, or configure a newly cloned or forked Lambda project.
+category: system
+tags: [scaffolding, template, init, aws, lambda, cur8d]
+---
+
+# Initialize Project from cur8d/lambda Template
+
+This skill guides you through transforming a newly cloned or forked `cur8d/lambda` repository into a fully personalized, standalone AWS Lambda project.
+
+## Prerequisites
+
+- Python 3.12+ and `uv` installed
+- `mise` installed
+- Clean git working tree
+
+## Workflow
+
+### 1. Gather Project Parameters
+Identify or ask the user for:
+- **Project Name** (kebab-case, e.g., `billing-service`)
+- **Description** (one-line summary, e.g., `Billing webhook and subscription processor`)
+- **Author Name** and **Email** (fallback to current git user: `git config user.name`, `git config user.email`)
+- **GitHub Username / Org** (e.g., `cur8d` or your personal handle)
+
+### 2. Execute Template Initialization
+Run the built-in initialization script using `uv`:
+
+```bash
+uv run python scripts/init.py \
+  --name "<project-name>" \
+  --description "<project-description>" \
+  --author "<author-name>" \
+  --email "<author-email>" \
+  --github "<github-username>"
+```
+
+The script will:
+- Rename `templates/` to the sanitized project package name (e.g. `billing_service/`).
+- Update package metadata in `pyproject.toml`.
+- Update repository references in `mkdocs.yml`, `.github/CODEOWNERS`, and documentation.
+- Remove `scripts/init.py` upon successful customization.
+
+### 3. Local Environment Configuration
+Copy the template local environment file:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Instruct the user or configure `LOCALSTACK_AUTH_TOKEN` if using LocalStack Pro features.
+
+### 4. Verify Baseline
+Run repository verification to ensure formatting, linting, and tests pass:
+
+```bash
+mise run verify
+```
+
+## Boundaries
+
+✅ **Always do:**
+- Always run `mise run verify` after initialization to ensure all renamed imports resolve cleanly.
+- Always verify git config values before prompting the user for author information.
+- Always copy `.env.local.example` to `.env.local`.
+
+🚫 **Never do:**
+- Never run the initialization script with empty or invalid names (only alphanumeric characters, dashes, and underscores are allowed).
+- Never push initial changes to the upstream `cur8d/lambda` template repo; ensure git remotes point to the user's repository.

.agents/skills/local-invoke/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: local-invoke
+description: Generates synthetic event payloads and tests Lambda function execution locally using LocalStack. Use whenever the user asks to test, invoke, or debug a Lambda function or CDK stack locally.
+category: coding
+tags: [aws, lambda, localstack, testing, invoke, cur8d]
+---
+
+# Test and Invoke Lambda Locally with LocalStack
+
+This skill guides you through spinning up LocalStack, deploying the target CDK stack locally, generating test event payloads, and invoking the Lambda function without hitting AWS cloud.
+
+## Prerequisites
+
+- Docker installed and running
+- `.env.local` configured (copied from `.env.local.example`)
+- `mise` installed
+
+## Workflow
+
+### 1. Start LocalStack
+Launch the local AWS emulation container:
+
+```bash
+mise run local:up
+```
+
+Verify that the LocalStack gateway is responding at `http://localhost:4566`:
+
+```bash
+curl -s http://localhost:4566/_localstack/health | jq .
+```
+
+### 2. Deploy Stack to LocalStack
+Deploy the target stack locally using `aws-cdk-local`:
+
+```bash
+mise run local:deploy <stack_name>
+```
+
+*(You can also use the shorthand alias `mise run local <stack_name>` or `dl <stack_name>`)*
+
+### 3. Generate Event Payload
+Synthesize a JSON test event matching the Lambda's trigger. For example:
+
+**API Gateway HTTP Payload:**
+```json
+{
+  "version": "2.0",
+  "routeKey": "POST /items",
+  "rawPath": "/items",
+  "headers": {
+    "content-type": "application/json"
+  },
+  "body": "{\"name\": \"sample-item\", \"value\": 42}",
+  "isBase64Encoded": false
+}
+```
+
+**SQS Message Payload:**
+```json
+{
+  "Records": [
+    {
+      "messageId": "msg-12345",
+      "body": "{\"action\": \"process\", \"id\": 1}",
+      "eventSource": "aws:sqs"
+    }
+  ]
+}
+```
+
+Save payload to a temporary file (e.g. `/tmp/event.json`).
+
+### 4. Invoke the Function
+Invoke using AWS CLI pointing to the local endpoint:
+
+```bash
+aws --endpoint-url=http://localhost:4566 lambda invoke \
+  --function-name <function_name> \
+  --payload fileb:///tmp/event.json \
+  /tmp/response.json
+```
+
+Inspect the output:
+```bash
+cat /tmp/response.json
+```
+
+### 5. Teardown / Cleanup
+When testing is complete:
+
+```bash
+# Tear down the stack
+mise run local:destroy <stack_name>
+
+# Stop LocalStack container
+mise run local:down
+```
+
+## Boundaries
+
+✅ **Always do:**
+- Always ensure LocalStack is up before deploying or invoking (`mise run local:up`).
+- Always pass `--endpoint-url=http://localhost:4566` when using AWS CLI for local testing.
+- Always clean up temporary payload files.
+
+🚫 **Never do:**
+- Never commit secret API tokens or sensitive production data in test payload files.
+- Never deploy to real AWS when local testing is intended.

.agents/skills/new-lambda/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: new-lambda
+description: Scaffolds a new event-driven AWS Lambda function adhering to cur8d standards with Powertools (Logger, Tracer, Metrics), Pydantic models, unit tests, and CDK infrastructure stack. Use whenever the user asks to create, scaffold, or add a Lambda function or service.
+category: coding
+tags: [aws, lambda, cdk, python, powertools, cur8d]
+---
+
+# Create New Lambda Function in cur8d/lambda
+
+This skill guides you through scaffolding, implementing, and registering a new AWS Lambda function and its corresponding AWS CDK infrastructure stack in `cur8d/lambda`.
+
+## Prerequisites
+
+- Python 3.12+ and `uv` installed
+- `mise` installed
+- Docker installed and running (for local test invoke via LocalStack)
+
+## Workflow
+
+### 1. Scaffold Boilerplate Files
+Run the built-in generator script with the function name (in snake_case or kebab-case):
+
+```bash
+uv run python scripts/new.py --name <function_name>
+```
+
+This generates:
+- `templates/<function_name>/handler.py` (Lambda handler entry point)
+- `templates/<function_name>/models.py` (Pydantic payload/event models)
+- `templates/<function_name>/settings.py` (Environment variables and settings via Pydantic)
+- `tests/<function_name>/test_handler.py` (Pytest test suite)
+- `infra/stacks/<function_name>.py` (AWS CDK Stack definition)
+- `docs/template/<function_name>.md` & `docs/reference/<function_name>.md` (Documentation)
+- Updates `infra/app.py` to register the new stack in `STACK_REGISTRY`.
+
+### 2. Implement Handler Logic & Models
+In `templates/<function_name>/handler.py`:
+- Use AWS Lambda Powertools decorators:
+  ```python
+  from aws_lambda_powertools import Logger, Metrics, Tracer
+
+  logger = Logger()
+  tracer = Tracer()
+  metrics = Metrics()
+
+
+  @logger.inject_lambda_context(log_event=True)
+  @tracer.capture_lambda_handler
+  @metrics.log_metrics(capture_cold_start_metric=True)
+  def lambda_handler(event: dict, context) -> dict: ...
+  ```
+- Define typed request/event models in `models.py` using Pydantic.
+- Define environment settings in `settings.py` using `pydantic_settings.BaseSettings`.
+
+### 3. Configure the CDK Stack
+In `infra/stacks/<function_name>.py`:
+- Customize runtime settings (memory size, timeout, log retention).
+- Wire triggers according to event source (API Gateway, SQS Queue, S3 Event, EventBridge rule, DynamoDB Streams).
+- Configure IAM permissions with least privilege.
+
+### 4. Implement Unit Tests
+In `tests/<function_name>/test_handler.py`:
+- Test successful execution with nominal mock event payloads.
+- Test invalid event schemas (expect appropriate validation errors).
+- Test error handling and cold start resilience.
+
+### 5. Verify Quality Gates
+Run repository verification:
+
+```bash
+mise run verify
+```
+
+Ensure formatting (`ruff format`), linting (`ruff check`), type checks, and pytest tests pass.
+
+## Boundaries
+
+✅ **Always do:**
+- Always decorate handlers with `@logger.inject_lambda_context`, `@tracer.capture_lambda_handler`, and `@metrics.log_metrics`.
+- Always register the new CDK stack in `infra/app.py`'s `STACK_REGISTRY`.
+- Always verify all checks pass with `mise run verify` before committing.
+
+🚫 **Never do:**
+- Never hardcode AWS credentials, account IDs, or region names in handlers or stacks.
+- Never write handlers without companion unit tests in `tests/<function_name>/`.