// Development workflow guide. Covers build, test, lint, format commands, package structure, Git hooks, TDD methodology, and coding conventions. Use when setting up dev environment, running tests, or following project conventions.
References Serverless OpenClaw architecture. Covers network design, CDK stack structure, DynamoDB data model, API protocols, and container design.
References cold start optimization history and techniques. Covers Docker image optimization, Fargate CPU tuning, SOCI lazy loading, and Lambda Bedrock discovery fix. Use when optimizing startup performance.
Loads Serverless OpenClaw project context. Provides background knowledge needed for development including project overview, tech stack, architecture decisions, and data models.
References Serverless OpenClaw cost optimization guidelines. Validates that no resources exceeding the cost target ($1/month) are created during implementation. Use when writing CDK stacks or making infrastructure changes.
Guides Phase 1 MVP implementation steps. Pass a specific step number as an argument to get the goals, deliverables, validation criteria, and detailed design for that step.
Guides Phase 2 Lambda Container Migration steps. Pass a specific step number (2-1 through 2-5) to get the goals, deliverables, validation criteria, and detailed design for that step.
| name | dev |
| description | Development workflow guide. Covers build, test, lint, format commands, package structure, Git hooks, TDD methodology, and coding conventions. Use when setting up dev environment, running tests, or following project conventions. |
| allowed-tools | Read, Bash, Glob, Grep |
Full guide: docs/development.md
npm run build # tsc --build (all packages via project references)
npm run lint # eslint "packages/**/*.ts"
npm run format # prettier
npm run test # vitest run (unit tests, excludes *.e2e.test.ts)
npm run test:e2e # vitest e2e (CDK synth E2E tests)
npm run skills:sync # sync shared skills into Claude/Codex mirrors
npm run skills:check # verify shared skill mirrors are in sync
# Single test file
npx vitest run packages/gateway/__tests__/handlers/ws-connect.test.ts
# Single test by name
npx vitest run -t "should verify JWT"
packages/
āāā shared/ # Types + constants (TABLE_NAMES, BRIDGE_PORT, key prefixes)
āāā cdk/ # CDK stacks (lib/stacks/)
āāā gateway/ # 7 Lambda handlers (ws-connect/message/disconnect, telegram-webhook, api-handler, watchdog, prewarm)
āāā container/ # Fargate container (Bridge server + OpenClaw JSON-RPC client)
āāā lambda-agent/ # Lambda agent (Phase 2 ā OpenClaw embedded in Lambda)
āāā web/ # React SPA (Vite, amazon-cognito-identity-js for auth)
| Hook | Checks |
|---|---|
pre-commit | npm run build + npm run lint + unit tests |
pre-push | E2E tests (CDK synth verification) |
webpackages/<pkg>/__tests__/packages/<pkg>/__tests__/*.e2e.test.tsTypeScript uses NodeNext module resolution. All imports must use .js extension:
// Correct
import { TABLE_NAMES } from "@serverless-openclaw/shared/constants.js";
import { routeMessage } from "../services/message.js";
// Wrong ā omitting .js will fail at runtime
import { TABLE_NAMES } from "@serverless-openclaw/shared/constants";
send function (same pattern as container package)ddb.send.bind(ddb) as (cmd: any) => Promise<any> cast neededvi.hoisted() when referencing variables in module-level mocks"*" for local dependencies ("workspace:*" is pnpm-only)