pywf AWS Lambda Project Conventions

---

name: pywf-aws-lbd-base description: "Conventions of the pywf AWS Lambda project template (v0.2.1), one topic per reference: runtime, environment, the config model, names, and loading, the boto session, the one singleton; then the Lambda code (handlers, dependencies, tests), the devops environment, the config in SSM; the CDK part (layout, StackCtxEnum / StackEnum, stack exports, generated mise tasks, synth-only tests, change recipes); and shipping (source asset, layer, stacks, deploy flow, Lambda change recipes). Load it before changing a Lambda function, a dependency, config, credentials, a stack, a mise task, or a test in such a project, before deploying, or for a question about how it is organized."

The conventions of a multi-environment AWS Lambda project generated from the pywf AWS Lambda template, which extends the pywf AWS CDK template. A generated project already follows all of them; this skill says what they are, so changes keep them.

Version

Template 0.2.1, the version in the seed repo's pyproject.toml. Every link points to the git tag of that version: MacHu-GWU/cookiecutter_aws_lbd_demo-project at 0.2.1. If the project in front of you differs from the linked files, the project wins; tell the user.

Precedence

For the layout of stacks, follow references/15-cdk-stack-enums.md, not the multi-stack best practice of cdk_mate. For a library's API, use its own skill: pypi-cdk_mate, pypi-aws_lbd_art_builder_uv and pypi-aws_lbd_art_builder_core (layer and source build), pypi-simple_aws_ssm_parameter_store (config deploy), pypi-boto_session_manager, pypi-s3pathlib; and the aws-cdk-cli-ref skill for a cdk CLI option.

References

00 is how this skill is written. 01–08 are general and never mention Lambda or CDK. Then, from code to deployment: 09–13 the Lambda code, the devops environment, and the config in SSM (lbd-); 14–19 the CDK part (cdk-); 20–24 shipping the functions (lbd-). For a question, read only the file that covers it.

<!-- BEGIN references index: generated by scripts/update_skill_index.py, do not edit by hand -->

• Authoring This Skill (references/00-authoring.md): Read before adding, editing, or renaming any file of this skill, or copying it to another template.
• Project Layout (references/01-project-layout.md): Read when looking for where a general concern lives, or deciding where a new one goes.
• Runtime (references/02-runtime.md): Read when code must behave differently on a developer machine and in CI, or when adding a runtime.
• Environment (references/03-env.md): Read when code depends on the environment, when switching environments, or when adding one.
• Config Model (references/04-config-model.md): Read before adding or changing a config field, or when deciding whether a value belongs in the config.
• Names in the Config (references/05-config-names.md): Read before naming any AWS resource, or before writing a name, ARN, or URL as a string anywhere else.
• Boto Session (references/06-boto-session.md): Read when code needs AWS credentials or a boto3 client, when setting up profiles, or when credentials go to the wrong account.
• Config Loading (references/07-config-load.md): Read when loading the config, adding or changing a config file, adding a config source, or when a config value is missing.
• The one Singleton (references/08-one-singleton.md): Read before adding a project-level object, a client, or anything environment specific, or when code imports a singleton from somewhere other than one.
• Lambda Handlers (references/09-lbd-handlers.md): Read before writing, renaming, or reviewing a Lambda function.
• Lambda Dependencies and Imports (references/10-lbd-dependencies.md): Read before adding a dependency, importing a library, or reading the package version.
• Lambda Tests (references/11-lbd-tests.md): Read when writing or fixing a test of a Lambda function.
• The devops Environment (references/12-lbd-devops-env.md): Read before code or a task touches the devops account, or when setting up a machine to deploy.
• Lambda Config in SSM (references/13-lbd-config-ssm.md): Read before adding a config field a function reads, changing how a function loads its config, or running a config task.
• CDK Layout (references/14-cdk-layout.md): Read before writing or reviewing a stack, or when deciding where CDK code goes.
• Stack Enums (references/15-cdk-stack-enums.md): Read before adding, removing, or reordering a stack, or wiring one stack to another.
• Stack Exports (references/16-cdk-stack-exports.md): Read before adding or changing a stack output, or when another project needs a stack's values.
• CDK mise Tasks (references/17-cdk-mise-tasks.md): Read before running any cdk command or task, after changing the stacks or environments, or when editing mise.toml.
• CDK Tests (references/18-cdk-tests.md): Read when writing or fixing a CDK test.
• CDK Change Recipes (references/19-cdk-change-recipes.md): Read before adding or removing a stack, a resource, an output, a stack dependency, or an environment, or when checking that such a change is complete.
• Lambda Source Asset (references/20-lbd-source-asset.md): Read before changing which files are deployed, how the source is built, or when a deploy updates a function that did not change.
• Lambda Layer (references/21-lbd-layer.md): Read before building, publishing, granting, pinning, or deleting a layer version, or when a deploy fails on a layer.
• Lambda Stacks (references/22-lbd-stacks.md): Read before changing a Lambda function's infrastructure, its permissions, or its triggers.
• Lambda Deploy Flow (references/23-lbd-deploy-flow.md): Read before deploying, or when deciding which task a change needs.
• Lambda Change Recipes (references/24-lbd-change-recipes.md): Read before adding or removing a Lambda function, a trigger, a permission, a runtime dependency, a config field a function reads, or a workload environment, or when checking that such a change is complete.

<!-- END references index -->