Context

You are Codex, an AI coding agent. Your job is to follow the instructions in the AGENTS.md and execute tasks defined in the project_root/tasks directory. You must follow the instructions (ie tasks, rules, etc).

Technology Stack

• Application Code

  • TypeScript 5.8 Lambda handlers (ES Modules, Node 20 arm64, IMDSv2)

  • AWS Lambda Powertools v2.22 primitives integrated throughout:

    • @aws-lambda-powertools/logger – structured, JSON-formatted logging
    • @aws-lambda-powertools/metrics – custom and CloudWatch embedded metrics (EMF)
    • @aws-lambda-powertools/tracer – X-Ray auto-instrumentation & cold-start capture
    • @aws-lambda-powertools/parameters – cached access to SSM Parameter Store / Secrets Manager
    • @aws-lambda-powertools/parser – event-source–aware body parsing
    • @aws-lambda-powertools/validation – schema validation helpers (paired with Zod 3.25)

  • Business-logic service layer and DynamoDB data access (@aws-sdk/*)

  • Id generation via uuid, additional custom utilities as needed

• Infrastructure as Code

  • Terraform ≥ 1.8 (AWS provider ≈ 5.x)
  • HTTP API Gateway (HTTP APIs) front-end
  • AWS Lambda (Node 20, arm64) with Powertools layers or bundled deps
  • Amazon DynamoDB single-table (PAY_PER_REQUEST), GSI gsi1

• Build, Test & Lint

  • esbuild bundling (tree-shakes Powertools for minimal cold-start size)
  • Jest 29 + ts-jest for unit tests (Powertools utilities mock-friendly)
  • ESLint / Prettier for code quality; scripts: lint, test, build, deploy (Terraform apply)

• Observability & Validation

  • End-to-end tracing via Powertools Tracer (wrapping X-Ray)
  • Automatic structured logs and CloudWatch EMF metrics
  • Event and payload validation using Powertools Validation (+ Zod) and ajv

• Package Management

  • Deterministic builds via pinned versions in package.json; standard npm workflows

TASK

• Tasks are contained in markdown files in the project_root/tasks directory.
• The agent executes each task sequentially. ie TASK 01, TASK 02, TASK 03, etc.
• If task fails record the failure in the session memory.

Order	Task File	Objective
1	Task 01 – Generate Source Code for CRUD Serverless App.md	Scaffold and implement all TypeScript Lambda handlers, service layer, and validation logic.
2	Task 02 – Generate Unit Tests.md	Produce Jest unit & integration tests (≥ 90 % coverage) and one .http file per CRUD action, then run npm test.
3	Task 03 – Generate Terraform Infrastructure.md	Build Terraform under iac/ for API Gateway, Lambda, DynamoDB, remote-state placeholders, tags, and outputs.

Each task file template:

# TASK – <concise title>

## Goal
<Exactly what the agent must deliver>

## Inputs
<Any schemas, examples, session_memory files, or existing code references>

## Tools
| Tool ID | Shell Invocation | Purpose |
|---------|------------------|---------|
| …       | …                | …       |

## Acceptance Criteria
<Explicit pass/fail gates such as lint clean, tests green (≥ 90 % coverage), tflint OK, etc.>

## Deliverables
<Directories/files the agent must create or modify>

---

SESSION MEMORY

• Location : project_root/session_memory/

• Required Files

  • 00_initial_input.md — raw user prompt that started the run
  • NN_task_<##>_output.md — summary of each task’s deliverables
  • NN_task_<##>_decisions.md — key design decisions and rationale

• Workflow

  1. User submits task. Save human prompt as input in 00_initial_input.md.
  2. After finishing a task, write the corresponding output and decisions files.
  3. At the start of every task, load all existing session memory files as input.
  4. Past memory files are immutable; corrections are appended as new bullets in the latest decisions file.

---

Execution of TASKs

1. User triggers Task 01 with a strategic chain-of-thought prompt.
2. ServerlessArchitectBot

• Save user input session_memory/00_initial_input.md.
• Run Task 01 and store 01_task_01_output.md and 01_task_01_decisions.md.
• Run Task 02 and store 02_task_02_output.md and 02_task_02_decisions.md.
• Run Task 03 and store 03_task_03_output.md and 03_task_03_decisions.md.
• Update change_log.md with a new semantic version entry and output next steps.

---

RULES

Metadata Header

— Every source, test, and Terraform file must begin with JSDoc tags.

• Placement: Top of file, above any import or code statements.

• Enforcement: npm_lint fails if a header is missing or malformed.

• Version: Increment only when the file contents change.

• Date: UTC timestamp of the most recent change.

• Template

    /**
    * App: {{Application Name}}
    * Package: {{package}}
    * File: {{file name}}
    * Version: semantic versioning starting at 0.1.0
    * Author: {{author}}
    * Date: {{YYYY-MM-DDThh:mm:ssZ}}
    * Exports: {{ exported functions, types, and variables.}}
    * Description: Level-5 documentation of the class or function. Document each
    *              method or function in the file.
    */
  

Versioning Rules

  * Use **semantic versioning** (`MAJOR.MINOR.PATCH`).
  * Track changes each “AI turn” in `project_root/changelog.md`.
  * Start at **0.1.0**; update only when code or configuration changes.
  * Record only the sections that changed.

```markdown
# Version History

### 0.0.1 – 2025-06-08 06:58:24 UTC (main)

#### Task
<Task>

#### Changes
- Initial project structure and configuration.

### 0.0.2 – 2025-06-08 07:23:08 UTC (work)

#### Task
<Task>

#### Changes
- Add tsconfig for ui and api.
- Create src directories with unit-test folders.
- Add e2e test directory for Playwright.
```

ADR (Architecture Decision Record)

Purpose

The /adr folder captures concise, high-signal Architecture Decision Records whenever the AI coding agent (or a human) makes a non-obvious technical or architectural choice. Storing ADRs keeps the project’s architectural rationale transparent and allows reviewers to understand why a particular path was taken without trawling through commit history or code comments.

Location

project_root/adr/

When the Agent Must Create an ADR

Scenario	Example	Required?
Summarize Chain of Thought reasoning for the task	Documenting the decision flow: ① capture requirements for a low-latency, pay-per-request CRUD API → ② compare DynamoDB single-table vs. Aurora Serverless → ③ choose DynamoDB single-table with GSI on email for predictable access patterns and minimal ops overhead.	Yes
Selecting one library or pattern over plausible alternatives	Choosing Prisma instead of TypeORM	Yes
Introducing a new directory or module layout	Splitting customer domain into bounded contexts	Yes
Changing a cross-cutting concern	Switching error-handling strategy to functional Result types	Yes
Cosmetic or trivial change	Renaming a variable	Yes

Naming Convention

adr/YYYYMMDDnnn_<slugified-title>.md

• YYYYMMDD – calendar date in UTC
• nnn – zero-padded sequence number for that day
• slugified-title – short, lowercase, hyphen-separated summary

Example: adr/20250611_001_use-prisma-for-orm.md.

Minimal ADR Template

# {{ADR Title}}

**Status**: Proposed | Accepted | Deprecated

**Date**: {{YYYY-MM-DD}}

**Context**  
Briefly explain the problem or decision context.

**Decision**  
State the choice that was made.

**Consequences**  
List the trade-offs and implications (positive and negative).  

Git Workflow Conventions

Branch Naming

<type>/<short-description>-<ticket-id?>

Type	Purpose	Example
feat	New feature	feat/profile-photo-upload-T1234
fix	Bug fix	fix/login-csrf-T5678
chore	Tooling, build, or dependency updates	chore/update-eslint-T0021
docs	Documentation only	docs/api-error-codes-T0099
refactor	Internal change w/out behaviour change	refactor/db-repository-T0456
test	Adding or improving tests	test/profile-service-T0789
perf	Performance improvement	perf/query-caching-T0987

Rules

1. One branch per ticket or atomic change.
2. Never commit directly to main or develop.
3. Re-base on the target branch before opening a pull request.

---

Commit Messages (Conventional Commits)

AI Coding Agent Change:
<type>(<optional-scope>): <short imperative summary>
<BLANK LINE>
Optional multi-line body (wrap at 72 chars).
<BLANK LINE>
Refs: <ticket-id(s)>

Example:

feature(profile-ui): add in-place address editing

Allows users to update their address directly on the Profile Overview
card without navigating away. Uses optimistic UI and server-side
validation.

Refs: T1234

---

Pull-Request Summary Template

Copy this template into every PR description and fill in each placeholder.

# Summary
<!-- One-sentence description of the change. -->

# Details
* **What was added/changed?**
* **Why was it needed?**
* **How was it implemented?** (key design points)

# Related Tickets
- T1234 Profile Overview – In-place editing
- T1300 Validation Rules

# Checklist
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Linter passes
- [ ] Documentation updated

# Breaking Changes
<!-- List backward-incompatible changes, or “None” -->

# Codex Task Link