feat(aws-serverless): add aws-serverless plugin

.claude-plugin/marketplace.json

@@ -47,6 +47,37 @@
       "source": "./plugins/amazon-location-service",
       "tags": ["aws", "location", "maps", "geospatial"],
       "version": "1.0.0"
+    },
+    {
+      "category": "development",
+      "description": "Design, build, deploy, test, and debug serverless applications with AWS Serverless services.",
+      "keywords": [
+        "aws",
+        "aws agent skills",
+        "amazon",
+        "serverless",
+        "lambda",
+        "durable functions",
+        "development",
+        "sam",
+        "api gateway",
+        "eventbridge",
+        "step functions"
+      ],
+      "name": "aws-serverless",
+      "source": "./plugins/aws-serverless",
+      "tags": [
+        "aws",
+        "serverless",
+        "lambda",
+        "durable functions",
+        "development",
+        "sam",
+        "api gateway",
+        "eventbridge",
+        "step functions"
+      ],
+      "version": "1.0.0"
     }
   ]
 }

.github/CODEOWNERS

@@ -31,6 +31,7 @@ tools/                              @awslabs/agent-plugins-admins
 ## Plugins (alphabetically listed)
 
 plugins/amazon-location-service     @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers  @awslabs/agent-plugins-agent-plugins-amazon-location-service
+plugins/aws-serverless              @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers  @awslabs/agent-plugins-aws-serverless
 plugins/deploy-on-aws               @awslabs/agent-plugins-admins @awslabs/agent-plugins-maintainers  @awslabs/agent-plugins-deploy-on-aws
 
 ## File must end with CODEOWNERS file

README.md

@@ -30,6 +30,7 @@ To maximize the benefits of plugin-assisted development while maintaining securi
 | --------------------------- | ----------------------------------------------------------------------------------------------------------------- | --------- |
 | **deploy-on-aws**           | Deploy applications to AWS with architecture recommendations, cost estimates, and IaC deployment                  | Available |
 | **amazon-location-service** | Add maps, geocoding, routing, places search, and geospatial features to applications with Amazon Location Service | Available |
+| **aws-serverless**          | Build serverless applications with Lambda, API Gateway, EventBridge, Step Functions, and durable functions        | Available |
 
 ## Installation
 

plugins/aws-serverless/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "author": {
+    "name": "Amazon Web Services"
+  },
+  "description": "Design, build, deploy, test, and debug serverless applications with AWS Serverless services.",
+  "homepage": "https://github.com/awslabs/agent-plugins",
+  "keywords": [
+    "aws",
+    "lambda",
+    "durable functions",
+    "serverless",
+    "development",
+    "sam",
+    "api-gateway",
+    "eventbridge",
+    "step-functions"
+  ],
+  "license": "Apache-2.0",
+  "name": "aws-serverless",
+  "repository": "https://github.com/awslabs/agent-plugins",
+  "version": "1.0.0"
+}

plugins/aws-serverless/.mcp.json

@@ -0,0 +1,15 @@
+{
+  "mcpServers": {
+    "aws-serverless-mcp": {
+      "command": "uvx",
+      "args": [
+        "awslabs.aws-serverless-mcp-server@latest",
+        "--allow-write"
+      ],
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000
+    }
+  }
+}

plugins/aws-serverless/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-template.sh",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

plugins/aws-serverless/scripts/validate-template.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Validates SAM templates after editing template.yaml or template.yml.
+# Runs as a PostToolUse hook on Edit/Write operations.
+
+set -euo pipefail
+
+# Skip if jq is not installed
+if ! command -v jq &> /dev/null; then
+  echo '{"systemMessage": "jq not found — SAM template validation skipped. Install jq for automatic validation."}'
+  exit 0
+fi
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Only validate SAM template files
+case "$FILE_PATH" in
+  *template.yaml|*template.yml) ;;
+  *) exit 0 ;;
+esac
+
+# Skip if SAM CLI is not installed
+if ! command -v sam &> /dev/null; then
+  echo '{"systemMessage": "SAM CLI not found — template validation skipped. Install SAM CLI for automatic validation."}'
+  exit 0
+fi
+
+# Skip if file doesn't exist (deleted)
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+OUTPUT=$(sam validate --template "$FILE_PATH" --lint 2>&1) && STATUS=0 || STATUS=$?
+
+if [ $STATUS -eq 0 ]; then
+  echo '{"systemMessage": "SAM template validation and linting passed."}'
+else
+  FORMATTED=$(echo "$OUTPUT" | jq -Rs '{systemMessage: ("SAM template validation/linting failed:\n" + .)}' 2>/dev/null) || \
+    FORMATTED="{\"systemMessage\": \"SAM template validation/linting failed:\\n$OUTPUT\"}"
+  echo "$FORMATTED"
+fi
+
+exit 0

plugins/aws-serverless/skills/aws-lambda-durable-functions/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: aws-lambda-durable-functions
+description: >
+  Build resilient, long-running, multi-step applications with AWS Lambda durable functions with automatic state persistence, retry logic, and orchestration for long-running executions. Covers the critical replay model, step operations, wait/callback patterns, error handling with saga pattern, testing with LocalDurableTestRunner. Triggers on phrases like: lambda durable functions, workflow orchestration, state machines, retry/checkpoint patterns, long-running stateful Lambda functions, saga pattern, human-in-the-loop callbacks, and reliable serverless applications.
+---
+
+# AWS Lambda durable functions
+
+Build resilient multi-step applications and AI workflows that can execute for up to 1 year while maintaining reliable progress despite interruptions.
+
+## Onboarding
+
+### Step 1: Validate Prerequisites
+
+Before using AWS Lambda durable functions, verify:
+
+1. **AWS CLI** is installed (2.33.22 or higher) and configured:
+
+   ```bash
+   aws --version
+   aws sts get-caller-identity
+   ```
+
+2. **Runtime environment** is ready:
+   - For TypeScript/JavaScript: Node.js 22+ (`node --version`)
+   - For Python: Python 3.11+ (`python --version`. Note that currently only Lambda runtime environments 3.13+ come with the Durable Execution SDK pre-installed. 3.11 is the min supported Python version by the Durable SDK itself, however, you could use OCI to bring your own container image with your own Python runtime + Durable SDK.)
+
+3. **Deployment capability** exists (one of):
+   - AWS SAM CLI (`sam --version`) 1.153.1 or higher
+   - AWS CDK (`cdk --version`) v2.237.1 or higher
+   - Direct Lambda deployment access
+
+### Step 2: Select language and IaC framework
+
+### Language Selection
+
+Default: TypeScript
+
+Override syntax:
+
+- "use Python" → Generate Python code
+- "use JavaScript" → Generate JavaScript code
+
+When not specified, ALWAYS use TypeScript
+
+### IaC framework selection
+
+Default: CDK
+
+Override syntax:
+
+- "use CloudFormation" → Generate YAML templates
+- "use SAM" → Generate YAML templates
+
+When not specified, ALWAYS use CDK
+
+### Error Scenarios
+
+#### Unsupported Language
+
+- List detected language
+- State: "Durable Execution SDK is not yet available for [framework]"
+- Suggest supported languages as alternatives
+
+#### Unsupported IaC Framework
+
+- List detected framework
+- State: "[framework] might not support Lambda durable functions yet"
+- Suggest supported frameworks as alternatives
+
+### Serverless MCP Server Unavailable
+
+- Inform user: "AWS Serverless MCP not responding"
+- Ask: "Proceed without MCP support?"
+- DO NOT continue without user confirmation
+
+### Step 3: Install SDK
+
+**For TypeScript/JavaScript:**
+
+```bash
+npm install @aws/durable-execution-sdk-js
+npm install --save-dev @aws/durable-execution-sdk-js-testing
+```
+
+**For Python:**
+
+```bash
+pip install aws-durable-execution-sdk-python
+pip install aws-durable-execution-sdk-python-testing
+```
+
+## When to Load Reference Files
+
+Load the appropriate reference file based on what the user is working on:
+
+- **Getting started**, **basic setup**, **example**, **ESLint**, or **Jest setup** -> see [getting-started.md](references/getting-started.md)
+- **Understanding replay model**, **determinism**, or **non-deterministic errors** -> see [replay-model-rules.md](references/replay-model-rules.md)
+- **Creating steps**, **atomic operations**, or **retry logic** -> see [step-operations.md](references/step-operations.md)
+- **Waiting**, **delays**, **callbacks**, **external systems**, or **polling** -> see [wait-operations.md](references/wait-operations.md)
+- **Parallel execution**, **map operations**, **batch processing**, or **concurrency** -> see [concurrent-operations.md](references/concurrent-operations.md)
+- **Error handling**, **retry strategies**, **saga pattern**, or **compensating transactions** -> see [error-handling.md](references/error-handling.md)
+- **Advanced error handling**, **timeout handling**, **circuit breakers**, or **conditional retries** -> see [advanced-error-handling.md](references/advanced-error-handling.md)
+- **Testing**, **local testing**, **cloud testing**, **test runner**, or **flaky tests** -> see [testing-patterns.md](references/testing-patterns.md)
+- **Deployment**, **CloudFormation**, **CDK**, **SAM**, **log groups**, **deploy**, or **infrastructure** -> see [deployment-iac.md](references/deployment-iac.md)
+- **Advanced patterns**, **GenAI agents**, **completion policies**, **step semantics**, or **custom serialization** -> see [advanced-patterns.md](references/advanced-patterns.md)
+- **troubleshooting**, **stuck execution**, **failed execution**, **debug execution ID**, or **execution history** -> see [troubleshooting-executions.md](references/troubleshooting-executions.md)
+
+## Quick Reference
+
+### Basic Handler Pattern
+
+**TypeScript:**
+
+```typescript
+import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';
+
+export const handler = withDurableExecution(async (event, context: DurableContext) => {
+  const result = await context.step('process', async () => processData(event));
+  return result;
+});
+```
+
+**Python:**
+
+```python
+from aws_durable_execution_sdk_python import durable_execution, DurableContext
+
+@durable_execution
+def handler(event: dict, context: DurableContext) -> dict:
+    result = context.step(lambda _: process_data(event), name='process')
+    return result
+```
+
+### Critical Rules
+
+1. **All non-deterministic code MUST be in steps** (Date.now, Math.random, API calls)
+2. **Cannot nest durable operations** - use `runInChildContext` to group operations
+3. **Closure mutations are lost on replay** - return values from steps
+4. **Side effects outside steps repeat** - use `context.logger` (replay-aware)
+
+### Python API Differences
+
+The Python SDK differs from TypeScript in several key areas:
+
+- **Steps**: Use `@durable_step` decorator + `context.step(my_step(args))`, or inline `context.step(lambda _: ..., name='...')`. Prefer the decorator for automatic step naming.
+- **Wait**: `context.wait(duration=Duration.from_seconds(n), name='...')`
+- **Exceptions**: `ExecutionError` (permanent), `InvocationError` (transient), `CallbackError` (callback failures)
+- **Testing**: Use `DurableFunctionTestRunner` class directly - instantiate with handler, use context manager, call `run(input=...)`
+
+### Invocation Requirements
+
+Durable functions **require qualified ARNs** (version, alias, or `$LATEST`):
+
+```bash
+# Valid
+aws lambda invoke --function-name my-function:1 output.json
+aws lambda invoke --function-name my-function:prod output.json
+
+# Invalid - will fail
+aws lambda invoke --function-name my-function output.json
+```
+
+## IAM Permissions
+
+Your Lambda execution role MUST have the `AWSLambdaBasicDurableExecutionRolePolicy` managed policy attached. This includes:
+
+- `lambda:CheckpointDurableExecution` - Persist execution state
+- `lambda:GetDurableExecutionState` - Retrieve execution state
+- CloudWatch Logs permissions
+
+**Additional permissions needed for:**
+
+- **Durable invokes**: `lambda:InvokeFunction` on target function ARNs
+- **External callbacks**: Systems need `lambda:SendDurableExecutionCallbackSuccess` and `lambda:SendDurableExecutionCallbackFailure`
+
+## Validation Guidelines
+
+When writing or reviewing durable function code, ALWAYS check for these replay model violations:
+
+1. **Non-deterministic code outside steps**: `Date.now()`, `Math.random()`, UUID generation, API calls, database queries must all be inside steps
+2. **Nested durable operations in step functions**: Cannot call `context.step()`, `context.wait()`, or `context.invoke()` inside a step function — use `context.runInChildContext()` instead
+3. **Closure mutations that won't persist**: Variables mutated inside steps are NOT preserved across replays — return values from steps instead
+4. **Side effects outside steps that repeat on replay**: Use `context.logger` for logging (it is replay-aware and deduplicates automatically)
+
+When implementing or modifying tests for durable functions, ALWAYS verify:
+
+1. All operations have descriptive names
+2. Tests get operations by NAME, never by index
+3. Replay behavior is tested with multiple invocations
+4. Use `LocalDurableTestRunner` for local testing
+
+### MCP Server Configuration
+
+**Write access is enabled by default.** The plugin ships with `--allow-write` in `.mcp.json`, so the MCP server can create projects, generate IaC, and deploy on behalf of the user.
+
+Access to sensitive data (like Lambda and API Gateway logs) is **not** enabled by default. To grant it, add `--allow-sensitive-data-access` to `.mcp.json`.
+
+## Resources
+
+- [AWS Lambda durable functions Documentation](https://docs.aws.amazon.com/lambda/latest/dg/durable-functions.html)
+- [JavaScript SDK Repository](https://github.com/aws/aws-durable-execution-sdk-js)
+- [Python SDK Repository](https://github.com/aws/aws-durable-execution-sdk-python)
+- [IAM Policy Reference](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLambdaBasicDurableExecutionRolePolicy.html)