diff --git a/.agents/skills/deploy-aws/SKILL.md b/.agents/skills/deploy-aws/SKILL.md new file mode 100644 index 0000000..7e11fa1 --- /dev/null +++ b/.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 +``` + +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 +``` + +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/ --since 5m --follow + ``` + +### 6. Teardown / Destruction (If Requested) +To tear down the deployed stack: + +```bash +mise run destroy +``` + +## 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 ` 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. diff --git a/.agents/skills/init-project/SKILL.md b/.agents/skills/init-project/SKILL.md new file mode 100644 index 0000000..d381f2a --- /dev/null +++ b/.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 "" \ + --description "" \ + --author "" \ + --email "" \ + --github "" +``` + +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. diff --git a/.agents/skills/local-invoke/SKILL.md b/.agents/skills/local-invoke/SKILL.md new file mode 100644 index 0000000..0f7040b --- /dev/null +++ b/.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 +``` + +*(You can also use the shorthand alias `mise run local ` or `dl `)* + +### 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 \ + --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 + +# 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. diff --git a/.agents/skills/new-lambda/SKILL.md b/.agents/skills/new-lambda/SKILL.md new file mode 100644 index 0000000..761f34a --- /dev/null +++ b/.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 +``` + +This generates: +- `templates//handler.py` (Lambda handler entry point) +- `templates//models.py` (Pydantic payload/event models) +- `templates//settings.py` (Environment variables and settings via Pydantic) +- `tests//test_handler.py` (Pytest test suite) +- `infra/stacks/.py` (AWS CDK Stack definition) +- `docs/template/.md` & `docs/reference/.md` (Documentation) +- Updates `infra/app.py` to register the new stack in `STACK_REGISTRY`. + +### 2. Implement Handler Logic & Models +In `templates//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/.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//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//`. diff --git a/.vibe/specs/add-skills/design.md b/.vibe/specs/add-skills/design.md new file mode 100644 index 0000000..4afe4dd --- /dev/null +++ b/.vibe/specs/add-skills/design.md @@ -0,0 +1,106 @@ +# Design: Agent Skills for cur8d Lambda + +## Architecture Overview + +```mermaid +flowchart TD + User["Developer Prompt / Issue"] --> Agent["AI Agent (Claude Code, Cursor, Antigravity)"] + Agent --> Registry[".agents/skills/ Index"] + + subgraph Skills [".agents/skills/"] + Init["init-project"] + New["new-lambda"] + Local["local-invoke"] + Deploy["deploy-aws"] + end + + Registry --> Init & New & Local & Deploy + + Init -->|"Configures"| Repo["scripts/init.py
pyproject.toml, .env.local"] + New -->|"Scaffolds"| Code["scripts/new.py
templates//, infra/stacks/.py"] + Local -->|"Tests locally"| LocalStack["mise run local:deploy (LocalStack)"] + Deploy -->|"Deploys to AWS"| Cloud["mise run deploy (AWS CDK)"] +``` + +## Directory Structure + +```text +aws-lambda-templates/ +├── .agents/ +│ └── skills/ +│ ├── init-project/ +│ │ └── SKILL.md +│ ├── new-lambda/ +│ │ └── SKILL.md +│ ├── local-invoke/ +│ │ └── SKILL.md +│ └── deploy-aws/ +│ └── SKILL.md +├── infra/ +├── templates/ +├── scripts/ +└── mise.toml +``` + +## Skill Definitions + +### 1. `init-project` +- **Frontmatter**: + ```yaml + --- + name: init-project + description: Initializes and customizes a new AWS Lambda service repository from the cur8d/lambda template. Use whenever asked to initialize, bootstrap, or fork this template into a new project. + category: system + tags: [scaffolding, template, init, cur8d] + --- + ``` +- **Rules**: + - Prompts for or accepts `--project-name`, `--description`, `--author`. + - Executes `uv run python scripts/init.py` or updates `pyproject.toml` and documentation. + - Copies `.env.local.example` to `.env.local`. + +### 2. `new-lambda` +- **Frontmatter**: + ```yaml + --- + name: new-lambda + description: Scaffolds a new event-driven Lambda function with Powertools, Pydantic models, unit tests, and CDK infrastructure stack. Use whenever asked to create, scaffold, or add a new Lambda template or handler. + category: coding + tags: [aws, lambda, cdk, python, powertools, cur8d] + --- + ``` +- **Rules**: + - Leverages `uv run python scripts/new.py --name `. + - Configures event trigger (API, SQS, S3, EventBridge, DynamoDB). + - Enforces Powertools (`Logger`, `Tracer`, `Metrics`). + - Verifies with `mise run test`. + +### 3. `local-invoke` +- **Frontmatter**: + ```yaml + --- + name: local-invoke + description: Generates synthetic event payloads and tests Lambda execution locally using LocalStack. Use whenever asked to test, invoke, or debug a Lambda function locally. + category: coding + tags: [aws, lambda, localstack, testing, cur8d] + --- + ``` +- **Rules**: + - Uses `mise run local:up` and `mise run local:deploy `. + - Synthesizes event payload matching the trigger schema. + +### 4. `deploy-aws` +- **Frontmatter**: + ```yaml + --- + name: deploy-aws + description: Synthesizes, diffs, and deploys CDK Lambda stacks to AWS cloud environments using mise and CDK CLI. Use whenever asked to deploy, diff, or inspect cloud deployment for this Lambda service. + category: coding + tags: [aws, cdk, deploy, cloud, cur8d] + --- + ``` +- **Rules**: + - Validates AWS credentials with `aws sts get-caller-identity`. + - Requires pre-flight verification `mise run verify`. + - Previews changes with `mise run diff `. + - Executes deployment with `mise run deploy `. diff --git a/.vibe/specs/add-skills/plan.md b/.vibe/specs/add-skills/plan.md new file mode 100644 index 0000000..3f67dd7 --- /dev/null +++ b/.vibe/specs/add-skills/plan.md @@ -0,0 +1,38 @@ +# Implementation Plan: Agent Skills for cur8d Lambda + +Establish structured Agent Skills in `cur8d/lambda` so AI coding agents can reliably initialize projects from the template, build and test new event-driven Lambda functions, invoke them locally, and deploy to AWS. + +## Proposed Changes + +### Skills Scaffolding + +#### [NEW] `.agents/skills/init-project/SKILL.md` +- Instructions for customizing the template into a standalone service repository using `scripts/init.py`. + +#### [NEW] `.agents/skills/new-lambda/SKILL.md` +- Instructions for scaffolding complete Lambda functions, tests, and CDK stacks using `scripts/new.py`. + +#### [NEW] `.agents/skills/local-invoke/SKILL.md` +- Instructions for local testing and execution against LocalStack. + +#### [NEW] `.agents/skills/deploy-aws/SKILL.md` +- Instructions for pre-flight verification, diffing, and deploying CDK stacks to AWS cloud. + +--- + +### Documentation & Agents Guidance + +#### [MODIFY] `AGENTS.md` +- Document the newly introduced skills under `.agents/skills/`. +- Provide guidance on using `npx skills add cur8d/lambda` or invoking skills directly. + +#### [MODIFY] `docs/README.md` +- Add an "Agent Skills" section explaining how developers and agents can consume the repository's built-in skills. + +--- + +### Verification Plan + +#### Automated Verification +- Run `mise run verify` (linting with ruff, type checks, and pytest suite execution). +- Run `npx skills ls` to confirm skills are detected by the skills CLI. diff --git a/.vibe/specs/add-skills/requirements.md b/.vibe/specs/add-skills/requirements.md new file mode 100644 index 0000000..2a45811 --- /dev/null +++ b/.vibe/specs/add-skills/requirements.md @@ -0,0 +1,55 @@ +# Requirements: Agent Skills for cur8d Lambda + +## Overview + +Equip the `cur8d/lambda` repository with modular Agent Skills following the open standard (compatible with `skills.sh`, Claude Code, Cursor, GitHub Copilot, and Google Antigravity). These skills enable AI agents to autonomously initialize new projects from this template, scaffold new event-driven Lambda functions with CDK stacks, invoke them locally via LocalStack, and deploy to AWS. + +## User Goals + +1. Enable developers and AI agents to initialize a new standalone Lambda service repository from this template with customized project name, description, and repository configuration. +2. Enable agents to scaffold new event handlers (API Gateway, SQS, EventBridge, S3, DynamoDB) adhering to cur8d's AWS Lambda Powertools conventions, Pydantic validation models, and automated tests. +3. Enable agents to invoke and test handlers locally using LocalStack (`mise run local:deploy`, `mise run local:up`). +4. Enable agents to safely synthesize, diff, and deploy CDK stacks to live AWS cloud accounts (`mise run diff`, `mise run deploy`). +5. Support distribution via `npx skills add cur8d/lambda` and project-level discovery under `.agents/skills/`. + +## Functional Requirements + +1. **`init-project` Skill**: + - Location: `.agents/skills/init-project/SKILL.md` + - Guides the agent through customizing the template into a new standalone repository. + - Runs `uv run python scripts/init.py` (or prompts for project name, description, author). + - Resets git remotes if forked, updates `pyproject.toml`, `infra/app.py`, and documentation. + - Sets up `.env.local` from `.env.local.example`. + +2. **`new-lambda` Skill**: + - Location: `.agents/skills/new-lambda/SKILL.md` + - Guides the agent to scaffold a complete new Lambda service: + - Generates handler under `templates//handler.py` with AWS Lambda Powertools (`Logger`, `Tracer`, `Metrics`). + - Generates settings and Pydantic models under `templates//settings.py` and `models.py`. + - Generates matching CDK infrastructure stack under `infra/stacks/.py` and registers it in `infra/app.py`. + - Generates comprehensive unit tests under `tests//test_handler.py`. + - Can invoke `uv run python scripts/new.py --name `. + +3. **`local-invoke` Skill**: + - Location: `.agents/skills/local-invoke/SKILL.md` + - Instructions to create synthetic event payloads and test local Lambda invocation. + - Guides the agent to start LocalStack (`mise run local:up`), deploy stack locally (`mise run local:deploy `), and invoke handler. + +4. **`deploy-aws` Skill**: + - Location: `.agents/skills/deploy-aws/SKILL.md` + - Step-by-step guidance for deploying stacks to live AWS cloud: + 1. Verify credentials and target AWS region (`aws sts get-caller-identity`). + 2. Run `mise run verify` to ensure tests and linters pass before deployment. + 3. Inspect changes via `mise run diff `. + 4. Deploy via `mise run deploy `. + 5. Verify deployment health and cloud outputs. + +5. **Integration & Discoverability**: + - Update `AGENTS.md` and `docs/README.md` to document the available skills and how to run them with `npx skills`. + +## Non-Functional Requirements + +- All skills must include valid YAML frontmatter (`name`, `description`, `category`, `tags`). +- Descriptions must be trigger-rich and action-oriented for progressive disclosure. +- Must keep each `SKILL.md` file concise (under 500 lines). +- Must adhere strictly to existing repository validation (`mise run verify` must pass). diff --git a/.vibe/specs/add-skills/tasks.md b/.vibe/specs/add-skills/tasks.md new file mode 100644 index 0000000..f00ed2c --- /dev/null +++ b/.vibe/specs/add-skills/tasks.md @@ -0,0 +1,10 @@ +# Tasks: Agent Skills for cur8d Lambda + +- [x] Create `.agents/skills/init-project/SKILL.md` +- [x] Create `.agents/skills/new-lambda/SKILL.md` +- [x] Create `.agents/skills/local-invoke/SKILL.md` +- [x] Create `.agents/skills/deploy-aws/SKILL.md` +- [x] Update `AGENTS.md` with skills inventory and triggering instructions +- [x] Update `docs/README.md` with Agent Skills documentation +- [x] Run `mise run verify` to ensure tests and linters pass +- [x] Verify skills discovery with `npx skills` diff --git a/AGENTS.md b/AGENTS.md index 0a2469f..cc1be79 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -206,3 +206,23 @@ if __name__ == "__main__": ### Lambda Entry Point - The main Lambda entry point should be named `main`. + +## Agent Skills + +This repository provides built-in modular skills following the open Agent Skills standard under `.agents/skills/`: + +| Skill | Purpose | Trigger / Usage | +| :--- | :--- | :--- | +| [`init-project`](.agents/skills/init-project/SKILL.md) | Initialize template into a standalone service | Initializing, bootstrapping, or configuring a new project from this repo | +| [`new-lambda`](.agents/skills/new-lambda/SKILL.md) | Scaffold event-driven Lambda with CDK stack and tests | Creating or adding a new Lambda template or handler | +| [`local-invoke`](.agents/skills/local-invoke/SKILL.md) | Test and invoke Lambda locally using LocalStack | Testing, invoking, or debugging Lambda execution locally | +| [`deploy-aws`](.agents/skills/deploy-aws/SKILL.md) | Diff and deploy CDK stacks to live AWS cloud | Deploying, diffing, or releasing CDK stacks to AWS | + +To discover or use skills with the `skills` CLI: +```bash +# List available skills +npx skills add cur8d/lambda --list + +# Install skills to current project +npx skills add cur8d/lambda +``` diff --git a/docs/README.md b/docs/README.md index 184ac94..d07dc01 100644 --- a/docs/README.md +++ b/docs/README.md @@ -44,6 +44,7 @@ Templates come pre-wired with: - **Pre-commit Validations**: [pre-commit](https://pre-commit.com) hooks - **Workflow Automation**: [GitHub Actions](https://github.com/features/actions) for CI/CD and documentation auto-deployment to [GitHub Pages](https://pages.github.com) - **Tool Management & Tasks**: [mise](https://mise.jdx.dev/) for managing project tools and automating common development tasks +- **Agent Skills**: Built-in modular AI agent skills under `.agents/skills/` compatible with [skills.sh](https://skills.sh), Claude Code, Cursor, and Google Antigravity ### GitHub files