# Naming Conventions

## The Rule

kebab-case for everything. No exceptions.

No `snake_case`, `PascalCase`, or mixed styles anywhere.

## Where It Applies

| Resource | Example |
|---|---|
| Repository names | `expense-approval-bot`, `door-unlock-api` |
| CloudFormation stack names | `expense-approval-bot` (must match repo name) |
| Lambda function names | `expense-approval-bot-process-receipt` |
| DynamoDB table names | `expense-approval-bot-receipts` |
| S3 bucket names | `expense-approval-bot-uploads` |
| Secrets Manager secrets | `expense-approval-bot/slack-signing` |
| Feature branches | `feature/add-receipt-parser` |
| HCP workspaces | `expense-approval-bot-dev`, `expense-approval-bot-prod` |
| HCP apply / plan roles | `hcptf-expense-approval-bot`, `hcptf-expense-approval-bot-plan` |
| GitHub deploy role | `githubdeploy-expense-approval-bot` |
| Deploy SSM prefix | `/expense-approval-bot/deploy/` |

## CDK Gotcha

CDK generates PascalCase stack names by default. Always set an explicit `stackName` (TypeScript) or `stack_name` (Python) in your stack definition to enforce kebab-case.

```typescript
new MyStack(app, 'MyStack', {
  stackName: 'my-stack',
});
```

## Examples

| Bad | Good | Why |
|---|---|---|
| `ExpenseApprovalBot` | `expense-approval-bot` | PascalCase |
| `expense_approval_bot` | `expense-approval-bot` | snake_case |
| `expenseApprovalBot` | `expense-approval-bot` | camelCase |
| `Expense-Approval-Bot` | `expense-approval-bot` | Mixed case |
| `feature/AddParser` | `feature/add-parser` | PascalCase in branch |

## Legacy Stacks

A handful of stacks predate this convention and remain PascalCase because renaming would require stack replacement (data loss, deploy windows). Examples in active use:

- `SeaHavenDoorUnlockStack`
- `WorkorderIngestStack`

Do not rename these solely to enforce kebab-case if doing so means tearing down and recreating production resources. New stacks must follow the convention; legacy stacks may keep their names until a planned migration brings them in line.