From fc135aa99af755a6bad9a9164f3404f01e44ba06 Mon Sep 17 00:00:00 2001 From: Amr Abed <3361565+amrabed@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:27:24 -0400 Subject: [PATCH 1/3] feat(spec): add specification for agent skills --- .vibe/specs/add-skills/design.md | 90 ++++++++++++++++++++++++++ .vibe/specs/add-skills/plan.md | 35 ++++++++++ .vibe/specs/add-skills/requirements.md | 43 ++++++++++++ .vibe/specs/add-skills/tasks.md | 9 +++ 4 files changed, 177 insertions(+) create mode 100644 .vibe/specs/add-skills/design.md create mode 100644 .vibe/specs/add-skills/plan.md create mode 100644 .vibe/specs/add-skills/requirements.md create mode 100644 .vibe/specs/add-skills/tasks.md diff --git a/.vibe/specs/add-skills/design.md b/.vibe/specs/add-skills/design.md new file mode 100644 index 0000000..41e033a --- /dev/null +++ b/.vibe/specs/add-skills/design.md @@ -0,0 +1,90 @@ +# 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/"] + H["add-lambda-handler"] + S["add-cdk-stack"] + I["local-invoke"] + end + + Registry --> H & S & I + + H -->|"Generates"| Code["templates//handler.py
tests/test_.py"] + S -->|"Generates"| Infra["infra/stacks/_stack.py
infra/app.py"] + I -->|"Invokes via"| LocalStack["LocalStack / mise run local:deploy"] + + Code & Infra --> Verify["mise run verify (ruff + pytest)"] +``` + +## Directory Structure + +Skills will be placed in `.agents/skills/` to ensure immediate compatibility with `skills.sh`, Claude Code, Cursor, and other agent platforms: + +```text +aws-lambda-templates/ +├── .agents/ +│ └── skills/ +│ ├── add-lambda-handler/ +│ │ └── SKILL.md +│ ├── add-cdk-stack/ +│ │ └── SKILL.md +│ └── local-invoke/ +│ ├── SKILL.md +│ └── templates/ +│ └── sample-event.json +├── infra/ +├── templates/ +└── mise.toml +``` + +## Skill Definitions + +### 1. `add-lambda-handler` +- **Frontmatter**: + ```yaml + --- + name: add-lambda-handler + description: Scaffolds a new AWS Lambda function handler adhering to cur8d standards with Powertools (Logger, Tracer, Metrics), Pydantic payload models, and unit tests. Use whenever asked to create, add, or implement a Lambda handler. + category: coding + tags: [aws, lambda, python, powertools, cur8d] + --- + ``` +- **Rules**: + - Requires `@logger.inject_lambda_context`, `@tracer.capture_lambda_handler`, `@metrics.log_metrics`. + - Requires Pydantic models in `models.py`. + - Requires pytest unit test in `tests/` with mocked AWS context. + +### 2. `add-cdk-stack` +- **Frontmatter**: + ```yaml + --- + name: add-cdk-stack + description: Creates a new AWS CDK infrastructure stack under infra/stacks/ wired to Lambda handlers, permissions, and event triggers. Use whenever asked to add AWS infrastructure, CDK stacks, or triggers for a Lambda. + category: coding + tags: [aws, cdk, infra, lambda, cur8d] + --- + ``` +- **Rules**: + - Inherits from `aws_cdk.Stack`. + - Configures memory, timeout, environment variables, log retention. + - Registers the stack in `infra/app.py`. + +### 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**: + - Leverages `mise run local:up` and `mise run local:deploy `. + - Formats payloads in accordance with AWS service event specs (APIGW proxy, SQS message, S3 event). diff --git a/.vibe/specs/add-skills/plan.md b/.vibe/specs/add-skills/plan.md new file mode 100644 index 0000000..9fc5a0a --- /dev/null +++ b/.vibe/specs/add-skills/plan.md @@ -0,0 +1,35 @@ +# Implementation Plan: Agent Skills for cur8d Lambda + +Establish structured Agent Skills in `cur8d/lambda` so AI coding agents can reliably build, extend, and verify AWS Lambda solutions and CDK infrastructure. + +## Proposed Changes + +### Skills Scaffolding + +#### [NEW] `.agents/skills/add-lambda-handler/SKILL.md` +- Provide actionable instructions for creating new Lambda handlers with Powertools (Logger, Tracer, Metrics), Pydantic validation, structured responses, and unit tests. + +#### [NEW] `.agents/skills/add-cdk-stack/SKILL.md` +- Provide step-by-step guidance for adding and wiring new CDK stacks under `infra/stacks/` and connecting them to `infra/app.py`. + +#### [NEW] `.agents/skills/local-invoke/SKILL.md` +- Provide instructions for generating synthetic event payloads and testing execution via LocalStack. + +--- + +### 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..efe743c --- /dev/null +++ b/.vibe/specs/add-skills/requirements.md @@ -0,0 +1,43 @@ +# 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 scaffold, test, and deploy Lambda event handlers and CDK infrastructure according to cur8d architecture patterns. + +## User Goals + +1. Enable developers and AI agents to quickly scaffold new Lambda handlers (API Gateway, SQS, EventBridge, S3, DynamoDB Stream) adhering to cur8d's AWS Lambda Powertools conventions and Pydantic validation. +2. Enable agents to generate matching CDK infrastructure stacks under `infra/stacks/` and register them in `infra/app.py`. +3. Provide local invocation and verification skills utilizing LocalStack and `mise` tasks (`mise run local:deploy`, `mise run verify`). +4. Support distribution via `npx skills add cur8d/lambda` and project-level discovery under `.agents/skills/`. + +## Functional Requirements + +1. **`add-lambda-handler` Skill**: + - Location: `.agents/skills/add-lambda-handler/SKILL.md` + - Instructions for the agent to scaffold a new handler under `templates//` or custom handler path. + - Must mandate AWS Lambda Powertools (`Logger`, `Tracer`, `Metrics`). + - Must mandate typed event models via Pydantic (`models.py`) and standard JSON responses. + - Must scaffold unit tests in `tests/test_.py` covering successful execution, invalid payloads, and error handling. + +2. **`add-cdk-stack` Skill**: + - Location: `.agents/skills/add-cdk-stack/SKILL.md` + - Instructions for the agent to scaffold a CDK stack in `infra/stacks/_stack.py`. + - Wires appropriate triggers (e.g. SQS queue, API Gateway REST/HTTP API, EventBridge bus rule, DynamoDB stream). + - Configures environment variables, least-privilege IAM policies, and registers the stack into `infra/app.py`. + +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 spin up LocalStack via `mise run local:up`, deploy with `mise run local:deploy `, and invoke using AWS CLI or local invoke scripts. + +4. **Integration & Discoverability**: + - Update `AGENTS.md` and `docs/README.md` to document the available skills and how to run them with `npx skills`. + - Add a mise task `mise run skills:list` or verify skills discoverability via `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..0da7703 --- /dev/null +++ b/.vibe/specs/add-skills/tasks.md @@ -0,0 +1,9 @@ +# Tasks: Agent Skills for cur8d Lambda + +- [ ] Create `.agents/skills/add-lambda-handler/SKILL.md` +- [ ] Create `.agents/skills/add-cdk-stack/SKILL.md` +- [ ] Create `.agents/skills/local-invoke/SKILL.md` +- [ ] Update `AGENTS.md` with skills inventory and triggering instructions +- [ ] Update `docs/README.md` with Agent Skills documentation +- [ ] Run `mise run verify` to ensure tests and linters pass +- [ ] Verify skills discovery with `npx skills` From e742639e51f3f8eabed357fa5a0de2bdd3390a23 Mon Sep 17 00:00:00 2001 From: Amr Abed <3361565+amrabed@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:41:14 -0400 Subject: [PATCH 2/3] docs(spec): add init-project and deploy-aws skills to lambda plan --- .vibe/specs/add-skills/design.md | 84 +++++++++++++++----------- .vibe/specs/add-skills/plan.md | 15 +++-- .vibe/specs/add-skills/requirements.md | 54 ++++++++++------- .vibe/specs/add-skills/tasks.md | 13 ++-- 4 files changed, 99 insertions(+), 67 deletions(-) diff --git a/.vibe/specs/add-skills/design.md b/.vibe/specs/add-skills/design.md index 41e033a..4afe4dd 100644 --- a/.vibe/specs/add-skills/design.md +++ b/.vibe/specs/add-skills/design.md @@ -8,72 +8,72 @@ flowchart TD Agent --> Registry[".agents/skills/ Index"] subgraph Skills [".agents/skills/"] - H["add-lambda-handler"] - S["add-cdk-stack"] - I["local-invoke"] + Init["init-project"] + New["new-lambda"] + Local["local-invoke"] + Deploy["deploy-aws"] end - Registry --> H & S & I + Registry --> Init & New & Local & Deploy - H -->|"Generates"| Code["templates//handler.py
tests/test_.py"] - S -->|"Generates"| Infra["infra/stacks/_stack.py
infra/app.py"] - I -->|"Invokes via"| LocalStack["LocalStack / mise run local:deploy"] - - Code & Infra --> Verify["mise run verify (ruff + pytest)"] + 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 -Skills will be placed in `.agents/skills/` to ensure immediate compatibility with `skills.sh`, Claude Code, Cursor, and other agent platforms: - ```text aws-lambda-templates/ ├── .agents/ │ └── skills/ -│ ├── add-lambda-handler/ +│ ├── init-project/ +│ │ └── SKILL.md +│ ├── new-lambda/ │ │ └── SKILL.md -│ ├── add-cdk-stack/ +│ ├── local-invoke/ │ │ └── SKILL.md -│ └── local-invoke/ -│ ├── SKILL.md -│ └── templates/ -│ └── sample-event.json +│ └── deploy-aws/ +│ └── SKILL.md ├── infra/ ├── templates/ +├── scripts/ └── mise.toml ``` ## Skill Definitions -### 1. `add-lambda-handler` +### 1. `init-project` - **Frontmatter**: ```yaml --- - name: add-lambda-handler - description: Scaffolds a new AWS Lambda function handler adhering to cur8d standards with Powertools (Logger, Tracer, Metrics), Pydantic payload models, and unit tests. Use whenever asked to create, add, or implement a Lambda handler. - category: coding - tags: [aws, lambda, python, powertools, cur8d] + 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**: - - Requires `@logger.inject_lambda_context`, `@tracer.capture_lambda_handler`, `@metrics.log_metrics`. - - Requires Pydantic models in `models.py`. - - Requires pytest unit test in `tests/` with mocked AWS context. + - 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. `add-cdk-stack` +### 2. `new-lambda` - **Frontmatter**: ```yaml --- - name: add-cdk-stack - description: Creates a new AWS CDK infrastructure stack under infra/stacks/ wired to Lambda handlers, permissions, and event triggers. Use whenever asked to add AWS infrastructure, CDK stacks, or triggers for a Lambda. + 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, cdk, infra, lambda, cur8d] + tags: [aws, lambda, cdk, python, powertools, cur8d] --- ``` - **Rules**: - - Inherits from `aws_cdk.Stack`. - - Configures memory, timeout, environment variables, log retention. - - Registers the stack in `infra/app.py`. + - 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**: @@ -86,5 +86,21 @@ aws-lambda-templates/ --- ``` - **Rules**: - - Leverages `mise run local:up` and `mise run local:deploy `. - - Formats payloads in accordance with AWS service event specs (APIGW proxy, SQS message, S3 event). + - 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 index 9fc5a0a..3f67dd7 100644 --- a/.vibe/specs/add-skills/plan.md +++ b/.vibe/specs/add-skills/plan.md @@ -1,19 +1,22 @@ # Implementation Plan: Agent Skills for cur8d Lambda -Establish structured Agent Skills in `cur8d/lambda` so AI coding agents can reliably build, extend, and verify AWS Lambda solutions and CDK infrastructure. +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/add-lambda-handler/SKILL.md` -- Provide actionable instructions for creating new Lambda handlers with Powertools (Logger, Tracer, Metrics), Pydantic validation, structured responses, and unit tests. +#### [NEW] `.agents/skills/init-project/SKILL.md` +- Instructions for customizing the template into a standalone service repository using `scripts/init.py`. -#### [NEW] `.agents/skills/add-cdk-stack/SKILL.md` -- Provide step-by-step guidance for adding and wiring new CDK stacks under `infra/stacks/` and connecting them to `infra/app.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` -- Provide instructions for generating synthetic event payloads and testing execution via LocalStack. +- 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. --- diff --git a/.vibe/specs/add-skills/requirements.md b/.vibe/specs/add-skills/requirements.md index efe743c..2a45811 100644 --- a/.vibe/specs/add-skills/requirements.md +++ b/.vibe/specs/add-skills/requirements.md @@ -2,38 +2,50 @@ ## 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 scaffold, test, and deploy Lambda event handlers and CDK infrastructure according to cur8d architecture patterns. +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 quickly scaffold new Lambda handlers (API Gateway, SQS, EventBridge, S3, DynamoDB Stream) adhering to cur8d's AWS Lambda Powertools conventions and Pydantic validation. -2. Enable agents to generate matching CDK infrastructure stacks under `infra/stacks/` and register them in `infra/app.py`. -3. Provide local invocation and verification skills utilizing LocalStack and `mise` tasks (`mise run local:deploy`, `mise run verify`). -4. Support distribution via `npx skills add cur8d/lambda` and project-level discovery under `.agents/skills/`. +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. **`add-lambda-handler` Skill**: - - Location: `.agents/skills/add-lambda-handler/SKILL.md` - - Instructions for the agent to scaffold a new handler under `templates//` or custom handler path. - - Must mandate AWS Lambda Powertools (`Logger`, `Tracer`, `Metrics`). - - Must mandate typed event models via Pydantic (`models.py`) and standard JSON responses. - - Must scaffold unit tests in `tests/test_.py` covering successful execution, invalid payloads, and error handling. - -2. **`add-cdk-stack` Skill**: - - Location: `.agents/skills/add-cdk-stack/SKILL.md` - - Instructions for the agent to scaffold a CDK stack in `infra/stacks/_stack.py`. - - Wires appropriate triggers (e.g. SQS queue, API Gateway REST/HTTP API, EventBridge bus rule, DynamoDB stream). - - Configures environment variables, least-privilege IAM policies, and registers the stack into `infra/app.py`. +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 spin up LocalStack via `mise run local:up`, deploy with `mise run local:deploy `, and invoke using AWS CLI or local invoke scripts. - -4. **Integration & Discoverability**: + - 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`. - - Add a mise task `mise run skills:list` or verify skills discoverability via `npx skills`. ## Non-Functional Requirements diff --git a/.vibe/specs/add-skills/tasks.md b/.vibe/specs/add-skills/tasks.md index 0da7703..6c0c4a1 100644 --- a/.vibe/specs/add-skills/tasks.md +++ b/.vibe/specs/add-skills/tasks.md @@ -1,9 +1,10 @@ # Tasks: Agent Skills for cur8d Lambda -- [ ] Create `.agents/skills/add-lambda-handler/SKILL.md` -- [ ] Create `.agents/skills/add-cdk-stack/SKILL.md` +- [ ] Create `.agents/skills/init-project/SKILL.md` +- [ ] Create `.agents/skills/new-lambda/SKILL.md` - [ ] Create `.agents/skills/local-invoke/SKILL.md` -- [ ] Update `AGENTS.md` with skills inventory and triggering instructions -- [ ] Update `docs/README.md` with Agent Skills documentation -- [ ] Run `mise run verify` to ensure tests and linters pass -- [ ] Verify skills discovery with `npx skills` +- [ ] Create `.agents/skills/deploy-aws/SKILL.md` +- [ ] Update `AGENTS.md` with skills inventory and triggering instructions +- [ ] Update `docs/README.md` with Agent Skills documentation +- [ ] Run `mise run verify` to ensure tests and linters pass +- [ ] Verify skills discovery with `npx skills` From 54c11da50902ffec8320440394b7b95bbcc2b1fb Mon Sep 17 00:00:00 2001 From: Amr Abed <3361565+amrabed@users.noreply.github.com> Date: Sat, 17 Oct 2026 20:45:17 -0400 Subject: [PATCH 3/3] feat(skills): implement agent skills for lambda template --- .agents/skills/deploy-aws/SKILL.md | 81 ++++++++++++++++++++ .agents/skills/init-project/SKILL.md | 70 +++++++++++++++++ .agents/skills/local-invoke/SKILL.md | 109 +++++++++++++++++++++++++++ .agents/skills/new-lambda/SKILL.md | 85 +++++++++++++++++++++ .vibe/specs/add-skills/tasks.md | 16 ++-- AGENTS.md | 20 +++++ docs/README.md | 1 + 7 files changed, 374 insertions(+), 8 deletions(-) create mode 100644 .agents/skills/deploy-aws/SKILL.md create mode 100644 .agents/skills/init-project/SKILL.md create mode 100644 .agents/skills/local-invoke/SKILL.md create mode 100644 .agents/skills/new-lambda/SKILL.md 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/tasks.md b/.vibe/specs/add-skills/tasks.md index 6c0c4a1..f00ed2c 100644 --- a/.vibe/specs/add-skills/tasks.md +++ b/.vibe/specs/add-skills/tasks.md @@ -1,10 +1,10 @@ # Tasks: Agent Skills for cur8d Lambda -- [ ] Create `.agents/skills/init-project/SKILL.md` -- [ ] Create `.agents/skills/new-lambda/SKILL.md` -- [ ] Create `.agents/skills/local-invoke/SKILL.md` -- [ ] Create `.agents/skills/deploy-aws/SKILL.md` -- [ ] Update `AGENTS.md` with skills inventory and triggering instructions -- [ ] Update `docs/README.md` with Agent Skills documentation -- [ ] Run `mise run verify` to ensure tests and linters pass -- [ ] Verify skills discovery with `npx skills` +- [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