| name | kl-engg-constitution |
| description | CAW Studios' engineering standards ("Playbooks" + "Patterns and Practices") that all projects should adhere to. Covers monorepo/modular-monolith structure, NestJS + FastAPI coding standards, API/Swagger/database/branch/ environment naming, event & service bus, logging/observability, exception handling, notifications, the provider pattern, and AWS/Terraform DevOps standards. Invoke when writing or reviewing code, designing a service or schema, naming branches/environments/resources, setting up a repo, or making AWS/IaC decisions on a CAW project — then read the specific reference file(s) relevant to the task. Triggers: "engineering constitution", "CAW standards", "playbook", "PnP", "our coding standards", "/kl-engg-constitution". |
CAW Engineering Constitution
The org-wide engineering standards for CAW Studios, synced from the
Engineering @ CAW Notion page (last synced 2026-06-22).
Philosophy
These practices are recommendations, not unbreakable rules. Context is
King — every problem is unique, so tweak the guidance as appropriate for the
product. The playbooks are living documents and will evolve.
Apply this judgement when using the references below: prefer the standard, but
deviate deliberately (and say why) when context warrants.
Precedence (when guidance conflicts)
Resolve any conflict between sources of guidance in this exact order:
- These CAW playbooks are the source of truth for CAW engineering standards.
For anything they cover — architecture, module boundaries, naming, API/DB
design, error handling, logging, events, providers, git workflow, Terraform,
AWS — the playbook wins over any other skill's guidance. If a third-party
skill suggests something that contradicts a playbook (e.g. test-first TDD,
snake_case plural tables, trunk-based git, deleting single-impl interfaces,
raw response bodies), follow the playbook.
- If the gstack skills are installed, they take precedence over other
third-party skills. Where a gstack skill overlaps a prerequisite skill
(e.g.
review/code-review/codex, investigate, ship, simplify,
health), prefer the gstack skill.
- Prerequisite skills fill remaining gaps only.
Prerequisite skills
This skill standardizes on a small, deliberately trimmed set of companion skills
(chosen after auditing many candidates for redundancy/conflict against these
playbooks). Before relying on them, verify they're installed — from this
skill's directory:
node prerequisites/install.mjs --check
If any are missing (or the check reports no lockfile), tell the user to install
them rather than silently relying on them:
node prerequisites/install.mjs
node prerequisites/install.mjs --groups core,frontend
node prerequisites/install.mjs --update
The prerequisites (see prerequisites/prerequisites.json):
- core (everyone):
prototype (runnable throwaway prototypes),
resolving-merge-conflicts.
- frontend (opt-in, Next.js teams only):
next-best-practices,
next-cache-components, next-upgrade. CAW mandates no frontend framework,
so these are not universal. If Next.js route handlers are used as a backend,
they MUST still follow the CAW API playbooks ({success,data,error} envelope,
/api/v1, no business logic in controllers).
Note: Claude Code has no native skill-dependency enforcement, so this is a
soft check — surface missing prerequisites to the user rather than failing
silently.
When to use
These standards target CAW "V1" projects, typically a monorepo with a
modular-monolith backend in NestJS (TypeScript) or FastAPI (Python),
deployed on AWS with Terraform. When working on such a project and the
task touches an area below, read the matching reference file before acting,
then follow it. Don't load files you don't need — pull only the relevant ones.
How to use
- Identify which standard(s) the task touches (table below).
- Read the corresponding file(s) in
references/.
- Apply the standard; flag any deliberate deviation to the user.
- For code review, check the diff against the relevant references.
Index
Repo setup & architecture
| Topic | Read when… | Reference |
|---|
| Agentic development workflow | Setting up / following the AI-assisted dev workflow | references/00-agentic-development-workflow.md |
| Monorepo standard | Creating or structuring a repo | references/01-monorepo-standard.md |
| Shared library best practices | Adding reusable code to /shared or /libs | references/02-shared-library-best-practices.md |
| Modular monolith structure | Designing modules / domain boundaries | references/03-modular-monolith-structure.md |
Backend
| Topic | Read when… | Reference |
|---|
| Coding standards (modular monolith) | Writing NestJS/FastAPI code; code review | references/pnp-coding-standards-modular-monolith.md |
| Event & Service Bus | Designing events, pub/sub, idempotency, retries | references/04-event-and-service-bus.md |
| Logging & observability | Adding logs, metrics, tracing, alerting | references/05-logging-and-observability.md |
| Logger & log transports | Choosing a logger / transports per environment | references/06-logger-and-log-transports.md |
| Exception handling | Catching, classifying, returning errors | references/07-exception-handling.md |
| Notification module | Building outbound notifications (email/SMS/push) | references/08-notification-module.md |
| Provider pattern | Integrating an external service (SMS, payments, KYC…) | references/pnp-provider-pattern-for-integration.md |
API & data
| Topic | Read when… | Reference |
|---|
| API standards | Designing or reviewing REST endpoints | references/pnp-api-standards.md |
| Swagger / OpenAPI docs | Documenting APIs | references/pnp-swagger-api-documentation-standards.md |
| Database standards | Naming/modeling tables, schemas, migrations | references/pnp-database-standards.md |
Conventions
| Topic | Read when… | Reference |
|---|
| Branch naming (Git Flow) | Naming branches / managing releases | references/pnp-branch-naming-standards.md |
| Environment naming | Naming environments | references/pnp-environment-naming-standards.md |
DevOps / AWS
| Topic | Read when… | Reference |
|---|
| AWS tagging & naming conventions | Naming/tagging AWS resources | references/aws-tagging-naming-conventions.md |
| AWS root credentials | Handling AWS account root credentials | references/aws-root-credentials-best-practices.md |
| AWS Organization Units & sub-accounts | Creating AWS accounts / OU hierarchy / SCPs | references/aws-organization-unit-sub-accounts.md |
| Terraform / IaC | Writing or reviewing Terraform | references/terraform-iac.md |
Notes
- Source of truth is the Notion workspace; this is a point-in-time snapshot.
Re-sync when the playbooks change.
- Some diagrams in the source were images and are marked
_[diagram omitted]_
in the references — consult Notion if a diagram's detail matters.
