feat: add AWS Lambda deployment target

.claude/CUSTOM-AGENTS-GUIDE.md

@@ -89,7 +89,7 @@ Integration testing, contract testing, load testing for APIs.
 
 ### devops-automator (blue)
 Docker, CI/CD pipeline generation, deployment automation.
-- **When to use:** Setting up Docker, creating CI/CD, deploying to Cloudflare Workers or Node.js
+- **When to use:** Setting up Docker, creating CI/CD, deploying to Cloudflare Workers, Node.js, or AWS Lambda
 - **Key capabilities:** Multi-stage Docker, GitHub Actions, wrangler deploy, PM2, health endpoints
 
 ---

.claude/agents/devops-automator.md

@@ -1,6 +1,6 @@
 ---
 name: devops-automator
-description: API deployment and CI/CD specialist for Docker, GitHub Actions, Cloudflare Workers, and Node.js deployments. Use when setting up deployment pipelines, configuring Docker, managing Workers deployments, or automating build processes.
+description: API deployment and CI/CD specialist for Docker, GitHub Actions, Cloudflare Workers, Node.js, and AWS Lambda deployments. Use when setting up deployment pipelines, configuring Docker, managing Workers deployments, deploying with SAM, or automating build processes.
 color: blue
 tools: Bash, Read, Write, Grep, MultiEdit
 ---

.claude/pipeline.config.json

@@ -68,7 +68,7 @@
     "noAnyTypes": true
   },
   "deployment": {
-    "targets": ["cloudflare-workers", "node-docker"],
+    "targets": ["cloudflare-workers", "node-docker", "aws-lambda"],
     "defaultTarget": "cloudflare-workers",
     "cloudflareWorkers": {
       "compatibilityDate": "2024-12-01",
@@ -86,6 +86,16 @@
       "processManager": "node",
       "multiStage": true
     },
+    "awsLambda": {
+      "runtime": "nodejs22.x",
+      "architecture": "arm64",
+      "memorySizeMb": 512,
+      "timeoutSeconds": 28,
+      "apiGatewayType": "http-api",
+      "bundler": "esbuild",
+      "framework": "sam",
+      "provisionedConcurrency": 0
+    },
     "cicd": {
       "provider": "github-actions",
       "runTests": true,

.claude/skills/deployment-config-generator/SKILL.md

@@ -3,10 +3,13 @@ name: deployment-config-generator
 description: >
   Generates deployment configuration based on the target platform specified in
   build-spec.json. For Cloudflare Workers, generates wrangler.toml with bindings.
-  For Node.js, generates Dockerfile and docker-compose.yml with PostgreSQL. Always
-  generates GitHub Actions CI/CD workflow and .env.example. Keywords: deploy,
-  deployment, wrangler, cloudflare, workers, docker, dockerfile, docker-compose,
-  github-actions, ci-cd, pipeline, env, configuration, infrastructure
+  For Node.js, generates Dockerfile and docker-compose.yml with PostgreSQL. For
+  AWS Lambda, generates a SAM template (API Gateway HTTP API), esbuild bundling
+  config, and an OIDC deploy workflow. Always generates GitHub Actions CI/CD
+  workflow and .env.example. Keywords: deploy, deployment, wrangler, cloudflare,
+  workers, docker, dockerfile, docker-compose, aws, lambda, sam, api-gateway,
+  serverless, esbuild, oidc, cold-start, github-actions, ci-cd, pipeline, env,
+  configuration, infrastructure
 ---
 
 # Deployment Config Generator (Phase 5)
@@ -42,7 +45,7 @@ const spec = JSON.parse(
   await readFile('.claude/plans/build-spec.json', 'utf-8'),
 );
 
-const target = spec.deployment.target; // 'cloudflare-workers' | 'node'
+const target = spec.deployment.target; // 'cloudflare-workers' | 'node' | 'aws-lambda'
 const authStrategy = spec.auth.strategy;
 ```
 
@@ -245,6 +248,105 @@ serve({
 });
 ```
 
+### Step 2c -- AWS Lambda Configuration
+
+If target is `aws-lambda`, generate a SAM template, esbuild bundling config, and
+the Lambda entry point. Canonical templates live in `templates/aws-lambda/`
+(`template.yaml`, `samconfig.toml`, `esbuild.config.mjs`, `deploy.yml`,
+`docker-compose.yml` for the local dev database).
+
+The Lambda entry point uses Hono's AWS Lambda adapter. The adapter ships inside
+the core `hono` package (`hono/aws-lambda`) -- there is no separate package to
+install:
+
+```typescript
+// api/src/lambda.ts
+import { handle } from 'hono/aws-lambda';
+import app from './index.js';
+
+export const handler = handle(app);
+```
+
+Key pieces of `api/template.yaml`:
+
+```yaml
+Globals:
+  Function:
+    Runtime: nodejs22.x
+    Architectures: [arm64]   # Graviton: cheaper, faster cold starts
+    MemorySize: 512          # CPU scales with memory; right-size with Power Tuning
+    Timeout: 28              # below API Gateway's hard 30s integration timeout
+
+Resources:
+  HttpApi:
+    Type: AWS::Serverless::HttpApi   # HTTP API (v2), NOT REST API
+    Properties:
+      StageName: $default
+
+  ApiFunction:
+    Type: AWS::Serverless::Function
+    Properties:
+      CodeUri: dist/                 # prebuilt esbuild bundle
+      Handler: lambda.handler
+      Events:
+        Root:
+          Type: HttpApi              # no Path/Method = $default catch-all;
+          Properties:                # Hono does the routing
+            ApiId: !Ref HttpApi
+```
+
+Bundling: `esbuild.config.mjs` produces a single minified `dist/lambda.mjs`
+(`pnpm build:lambda`). `sam deploy` zips and uploads `dist/` directly -- do not
+use `sam build` (its esbuild builder runs npm and conflicts with pnpm).
+
+Add the build/deploy scripts to package.json:
+
+```json
+{
+  "scripts": {
+    "build:lambda": "node esbuild.config.mjs",
+    "deploy": "pnpm run build:lambda && sam deploy"
+  }
+}
+```
+
+(Invoke as `pnpm run deploy` -- bare `pnpm deploy` is a pnpm built-in.)
+
+Cold start notes to include in the generated README:
+
+- Single-file esbuild bundle: no node_modules to unzip/resolve at init
+- arm64 + memory sizing (CPU scales with memory; benchmark with AWS Lambda
+  Power Tuning before raising the 512 MB floor)
+- Reuse module-scope DB connections across warm invocations; cap the pool at
+  `max: 1` per instance and point DATABASE_URL at RDS Proxy or a serverless
+  driver so Lambda concurrency cannot exhaust Postgres connections
+- Provisioned concurrency for latency-critical routes (SnapStart is not
+  available for Node.js runtimes)
+- Container-image alternative: AWS Lambda Web Adapter runs the Node.js server
+  build unchanged (useful past the 250 MB zip limit; slower cold starts)
+
+Deployment uses GitHub OIDC (no long-lived AWS keys). Generate
+`.github/workflows/deploy.yml` from `templates/aws-lambda/deploy.yml`:
+
+```yaml
+permissions:
+  id-token: write # required for OIDC federation
+  contents: read
+
+# ...
+
+- uses: aws-actions/setup-sam@v2
+  with:
+    use-installer: true
+- uses: aws-actions/configure-aws-credentials@v4
+  with:
+    role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+    aws-region: ${{ vars.AWS_REGION }}
+- run: >-
+    sam deploy --no-confirm-changeset --no-fail-on-empty-changeset
+    --parameter-overrides "DatabaseUrl=${{ secrets.DATABASE_URL }} JwtSecret=${{ secrets.JWT_SECRET }}"
+```
+
 ### Step 3 -- Generate GitHub Actions CI/CD
 
 ```yaml
@@ -339,6 +441,14 @@ jobs:
       # For Node.js / Docker:
       # - run: docker build -t myapi:${{ github.sha }} ./api
       # - run: docker push myapi:${{ github.sha }}
+      # For AWS Lambda (OIDC -- job also needs `permissions: id-token: write`,
+      # see Step 2c):
+      # - uses: aws-actions/setup-sam@v2
+      # - uses: aws-actions/configure-aws-credentials@v4
+      #   with:
+      #     role-to-assume: ${{ secrets.AWS_DEPLOY_ROLE_ARN }}
+      #     aws-region: ${{ vars.AWS_REGION }}
+      # - run: cd api && pnpm run build:lambda && sam deploy --no-confirm-changeset
 
   deploy-production:
     runs-on: ubuntu-latest
@@ -412,9 +522,13 @@ Ensure the API package.json has all necessary scripts:
 | Wrangler config | `api/wrangler.toml` | Cloudflare Workers deployment |
 | Dockerfile | `api/Dockerfile` | Node.js container build |
 | Docker Compose | `docker-compose.yml` | Full stack local/prod setup |
+| SAM template | `api/template.yaml` | AWS Lambda + API Gateway HTTP API stack |
+| SAM config | `api/samconfig.toml` | Stack name, region, deploy defaults |
+| esbuild config | `api/esbuild.config.mjs` | Single-file Lambda bundle build |
 | CI/CD workflow | `.github/workflows/ci.yml` | GitHub Actions pipeline |
+| Deploy workflow | `.github/workflows/deploy.yml` | OIDC-based AWS Lambda deploy (Lambda target) |
 | Env template | `.env.example` | Environment variable template |
-| Entry point | `api/src/index.ts` | Platform-specific server bootstrap |
+| Entry point | `api/src/index.ts` | Platform-specific server bootstrap (plus `api/src/lambda.ts` on Lambda) |
 
 ## Integration
 

.claude/skills/schema-intake/SKILL.md

@@ -84,7 +84,7 @@ continuing. Adapt follow-up questions based on responses.
 
 **Question 6 -- Deployment Target**
 > Where will this API be deployed?
-> Options: Cloudflare Workers (default), Node.js / Docker
+> Options: Cloudflare Workers (default), Node.js / Docker, AWS Lambda
 
 **Question 7 -- Additional Requirements** (optional)
 > Any special requirements? (pagination style, rate limiting, soft deletes, etc.)
@@ -294,7 +294,7 @@ interface BuildSpec {
     sourceType: 'file' | 'interview';
   };
   deployment: {
-    target: 'cloudflare-workers' | 'node';
+    target: 'cloudflare-workers' | 'node' | 'aws-lambda';
     runtime: string;
   };
   auth: {
@@ -553,7 +553,7 @@ function validateBuildSpec(spec: BuildSpec): string[] {
 | `tdd-from-schema` (Phase 2) | Reads `endpoints` and `auth` to generate test cases |
 | `route-generation` (Phase 3) | Reads `endpoints` to scaffold Hono route handlers |
 | `api-authentication` | Reads `auth` to configure JWT/API key middleware |
-| `deployment-config-generator` | Reads `deployment` to generate wrangler.toml or Dockerfile |
+| `deployment-config-generator` | Reads `deployment` to generate wrangler.toml, Dockerfile, or SAM template |
 | `api-documentation` | Reads the generated OpenAPI spec or regenerates from build-spec |
 
 ### Triggering the Next Phase

.github/workflows/ci.yml

@@ -166,7 +166,7 @@ jobs:
             fi
           done
 
-          for dir in templates/shared templates/cloudflare-workers templates/node-server templates/docker; do
+          for dir in templates/shared templates/cloudflare-workers templates/node-server templates/docker templates/aws-lambda; do
             if [ -d "$dir" ]; then
               echo "  $dir: OK"
             else
@@ -226,6 +226,10 @@ jobs:
         run: pnpm exec tsc --noEmit -p tsconfig.node.json
         working-directory: templates/snippets
 
+      - name: Type-check AWS Lambda snippets
+        run: pnpm exec tsc --noEmit -p tsconfig.lambda.json
+        working-directory: templates/snippets
+
   check-links:
     name: Check Markdown Links
     runs-on: ubuntu-latest

CLAUDE.md

@@ -4,15 +4,15 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-This is a **Claude Code-integrated API & backend development framework** providing specialized agents, skills, scripts, and schema-to-API conversion pipelines. Built with TypeScript, Hono (HTTP framework), Drizzle ORM, and PostgreSQL. Deployed to Cloudflare Workers or Node.js.
+This is a **Claude Code-integrated API & backend development framework** providing specialized agents, skills, scripts, and schema-to-API conversion pipelines. Built with TypeScript, Hono (HTTP framework), Drizzle ORM, and PostgreSQL. Deployed to Cloudflare Workers, Node.js, or AWS Lambda.
 
 Nerva is the backend counterpart to **Aurelius** (frontend framework).
 
 The framework is designed for:
 - Schema-first API development (OpenAPI spec to working API)
 - OpenAPI-to-working-API conversion with TDD-mandatory development
 - Comprehensive testing (integration tests, contract tests, load tests with k6)
-- Deployment to Cloudflare Workers or Node.js with Docker support
+- Deployment to Cloudflare Workers, Node.js (Docker), or AWS Lambda (SAM)
 - Full product lifecycle support (engineering, database, testing, DevOps, operations)
 
 ## Project Structure
@@ -38,6 +38,7 @@ project-root/
 │   ├── shared/             # ESLint, Prettier, TypeScript configs
 │   ├── cloudflare-workers/ # Wrangler config
 │   ├── node-server/        # Node.js server config
+│   ├── aws-lambda/         # SAM template, esbuild config, OIDC deploy workflow
 │   └── docker/             # Dockerfile, docker-compose
 ├── docs/
 │   ├── schema-to-api/      # Pipeline guide
@@ -57,7 +58,7 @@ project-root/
 
 ```bash
 # Setup a new API project
-./scripts/setup-project.sh my-api --cloudflare  # or --node
+./scripts/setup-project.sh my-api --cloudflare  # or --node / --lambda
 
 # Run tests with coverage
 ./scripts/run-tests.sh
@@ -232,7 +233,7 @@ Autonomous 10-phase pipeline that converts an OpenAPI specification into a worki
 - **Schema-first** — OpenAPI spec drives database schema, types, handlers, and tests
 - **Contract testing** — generated tests validate API responses against OpenAPI spec
 - **Load testing** — k6 scripts generated for performance-critical endpoints
-- **Multi-target deployment** — Cloudflare Workers, Node.js, Docker with single config change
+- **Multi-target deployment** — Cloudflare Workers, Node.js, Docker, AWS Lambda with single config change
 - **Type safety end-to-end** — Drizzle schema to Zod validators to TypeScript types
 - Quality gate: 80%+ coverage, TypeScript strict, security audit, bundle analysis
 - Resumable: TodoWrite tracks progress across interrupted sessions
@@ -487,9 +488,10 @@ pnpm drizzle-kit studio             # Open database GUI
 ```bash
 ./scripts/setup-project.sh my-api --cloudflare  # New Cloudflare Workers project
 ./scripts/setup-project.sh my-api --node         # New Node.js project
+./scripts/setup-project.sh my-api --lambda       # New AWS Lambda (SAM) project
 ```
 
 ---
 
-**Last Updated:** 2026-03-29
+**Last Updated:** 2026-06-11
 **Architecture:** 24 agents, 12 skills, 4 plugins + gh CLI, 9 scripts

README.md

@@ -17,7 +17,7 @@ A Claude Code-integrated API & backend development framework with TypeScript, Ho
 - **12 Development Skills** — Automated workflows for schema parsing, TDD, route generation, authentication, validation, documentation
 - **10-Phase Schema-to-API Pipeline** — Convert OpenAPI specs into fully working, tested API servers with a single command
 - **TDD-Mandatory Development** — Integration tests written before route handlers, hard gate enforced
-- **Dual Deployment Targets** — Cloudflare Workers (edge) or Node.js (Docker) with one config change
+- **Three Deployment Targets** — Cloudflare Workers (edge), Node.js (Docker), or AWS Lambda (SAM) with one config change
 - **Testing Stack** — Vitest, supertest, contract tests against OpenAPI, k6 load tests
 - **Schema-First Design** — Database schemas, types, and validators all derived from your API spec
 
@@ -37,7 +37,7 @@ cd Nerva
 pnpm install
 
 # Initialize a new API project
-./scripts/setup-project.sh my-api --cloudflare   # or --node
+./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda
 
 # Start development
 cd api && pnpm dev
@@ -175,6 +175,7 @@ Full catalog: [`.claude/CUSTOM-AGENTS-GUIDE.md`](.claude/CUSTOM-AGENTS-GUIDE.md)
 | `templates/shared/` | ESLint, Prettier, TypeScript, Vitest configs |
 | `templates/cloudflare-workers/` | Wrangler config with Hyperdrive |
 | `templates/node-server/` | Dockerfile + docker-compose with PostgreSQL |
+| `templates/aws-lambda/` | SAM template, esbuild config, OIDC deploy workflow |
 | `templates/docker/` | Extended Docker with Redis + pgAdmin |
 
 ## Part of the PMDS Framework Series

docs/onboarding/architecture.md

@@ -61,7 +61,7 @@ Shell scripts for common development tasks:
 
 | Script | Purpose |
 |--------|---------|
-| `setup-project.sh` | Initialize a new API project (--cloudflare or --node) |
+| `setup-project.sh` | Initialize a new API project (--cloudflare, --node, or --lambda) |
 | `run-tests.sh` | Vitest test suite with coverage |
 | `check-types.sh` | TypeScript strict mode checking |
 | `security-scan.sh` | Dependency and code security audit |
@@ -71,7 +71,7 @@ Shell scripts for common development tasks:
 | `generate-openapi-docs.sh` | Build API documentation |
 | `generate-client.sh` | Generate typed API client for frontends |
 
-### Templates (4 directories)
+### Templates (5 directories)
 
 Starter configurations for different deployment targets:
 
@@ -80,6 +80,7 @@ Starter configurations for different deployment targets:
 | `templates/shared/` | ESLint, Prettier, TypeScript, Vitest configs |
 | `templates/cloudflare-workers/` | Wrangler config with D1/KV/Hyperdrive bindings |
 | `templates/node-server/` | Dockerfile + docker-compose with PostgreSQL |
+| `templates/aws-lambda/` | SAM template (API Gateway HTTP API), esbuild config, OIDC deploy workflow |
 | `templates/docker/` | Extended Docker setup with Redis + pgAdmin |
 
 ## Pipelines

docs/onboarding/quickstart.md

@@ -32,7 +32,7 @@ If you have an OpenAPI specification file:
 
 ```bash
 # Initialize the project structure
-./scripts/setup-project.sh my-api --cloudflare   # or --node
+./scripts/setup-project.sh my-api --cloudflare   # or --node / --lambda
 
 # Open Claude Code and run the pipeline
 /build-from-schema path/to/openapi-spec.yaml

docs/schema-to-api/README.md

@@ -15,7 +15,7 @@ Convert an OpenAPI specification into a fully working, tested API server through
 | 7 | Validation Layer | Generate Zod schemas for request/response validation |
 | 8 | Auth & Security | Wire authentication middleware, CORS, rate limiting |
 | 9 | Documentation | Generate API docs, Swagger UI config, example responses |
-| 10 | Deployment Config | Produce Wrangler TOML, Dockerfile, or both |
+| 10 | Deployment Config | Produce Wrangler TOML, Dockerfile, or SAM template |
 
 ## Phase-by-Phase Deep Dive
 
@@ -102,12 +102,12 @@ Convert an OpenAPI specification into a fully working, tested API server through
 
 ### Phase 10: Deployment Config
 
-**What it does:** Produces deployment configuration files matching the target platform. For Cloudflare Workers: `wrangler.toml` with D1 bindings. For Node.js: `Dockerfile` with multi-stage build and `docker-compose.yml`.
+**What it does:** Produces deployment configuration files matching the target platform. For Cloudflare Workers: `wrangler.toml` with D1 bindings. For Node.js: `Dockerfile` with multi-stage build and `docker-compose.yml`. For AWS Lambda: `template.yaml` (SAM with an API Gateway HTTP API), `samconfig.toml`, esbuild bundle config, and an OIDC-based deploy workflow.
 
 - **Inputs:** Project structure, database config, environment variables
-- **Outputs:** `wrangler.toml` and/or `Dockerfile` + `docker-compose.yml`
+- **Outputs:** `wrangler.toml`, `Dockerfile` + `docker-compose.yml`, or `template.yaml` + `samconfig.toml` + `esbuild.config.mjs`
 - **Tools:** `deployment-config-generator` skill
-- **Config:** `pipeline.config.json` -- `deployment.target` (cloudflare, node, both)
+- **Config:** `pipeline.config.json` -- `deployment.target` (cloudflare, node, aws-lambda, both)
 
 ## Configuration