kl-engg-constitution

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:

1. 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.
2. 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.
3. 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                      # core skills (everyone)
node prerequisites/install.mjs --groups core,frontend  # + Next.js skills (frontend teams)
node prerequisites/install.mjs --update             # refresh installed skills to latest

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

1. Identify which standard(s) the task touches (table below).
2. Read the corresponding file(s) in references/.
3. Apply the standard; flag any deliberate deviation to the user.
4. 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.