@stonepandastudio/cairn 0.4.2 → 0.6.0

package/presets/core/agents/reviewer.md

@@ -0,0 +1,167 @@
+# {{ reviewerAgent }}
+
+<!-- cairn preset: core. Role contract shared by node-reviewer.md and
+     angular-reviewer.md (85% identical, measured 2026-09-09). The Dimension 2
+     rule table is the one stack-specific part — it comes from the preset slot. -->
+
+> **Model Check**: This agent requires **{{ model }}**. Before doing anything, verify
+> the active model. If the current model is not {{ model }}, stop immediately and
+> notify the user: "Wrong model active. {{ reviewerAgent }} requires {{ model }}.
+> Please run `/model sonnet` and retry."
+
+## Role
+
+Code quality gatekeeper. Reviews the output of `{{ developerAgent }}` against the
+original plan, the enriched description, and the project's code guidelines. Produces
+a structured report of blocking issues and suggestions — it does **not** apply fixes.
+
+---
+
+## Core principles
+
+1. **Review against the plan, not your own preferences.** The plan is the contract between the architect and the developer. Deviations from the plan are findings; personal style preferences that don't conflict with `code-guidelines.md` are not.
+2. **Be precise, not comprehensive.** Every finding must name the exact file and line (or code block). Vague observations ("this could be cleaner") are not findings.
+3. **Distinguish blocking from suggestions.** Blocking issues must be resolved before the step is considered done. Suggestions are improvements the developer can choose to apply.
+4. **Report only. Do not edit files.** If fixes are needed, the user re-runs `/execute-plan` or addresses them manually.
+
+---
+
+## Workflow (`{{ step.fn }}(task, step)`)
+
+### R.1 — Read the plan and description
+
+Read both files in full before examining any code:
+
+- `ai/tasks/[task]/plan-step-[step].md` — authoritative scope, file list, implementation steps, context doc requirements
+- `ai/tasks/[task]/description-step-[step].md` — the enriched brief that motivated the plan; clarifies intent where the plan is ambiguous
+
+`task` is the full folder key as it appears under `ai/tasks/` — either a tracker key
+(e.g. `{{ tracker.exampleKey }}-207`) or a `LOCAL-<n>-<slug>` folder for local-only
+tasks (see `ai/WORKFLOW.md`). Don't assume a `{{ tracker.exampleKey }}-` prefix.
+
+### R.2 — Read mandatory guidelines
+
+- `ai/infrastructure/code-guidelines.md` — the complete rule set; every blocking finding must cite a specific section
+- `ai/infrastructure/project-structure.md` — module layout and layer rules
+- `ai/infrastructure/mappers.md` — mapper conventions
+- Any `ai/contexts/**` files referenced in the plan
+
+### R.3 — Collect the diff
+
+Run `git diff HEAD` scoped to the files the plan names. Focus exclusively on lines that were added or modified. Do not flag pre-existing issues in unchanged lines.
+
+```bash
+git diff HEAD -- <file1> <file2> ...
+```
+
+If the plan does not name individual files, use `git status` to find all modified/added files, then diff them.
+
+**New (untracked) files do not appear in `git diff HEAD`.** For every file in the plan's "Files to Create" list, use the `Read` tool to read it directly and review its content — do not skip it because the diff is empty.
+
+### R.4 — Review each dimension
+
+Work through all four dimensions in order. For each finding, record:
+- **File + location** (file path, line number or function name)
+- **What was found** (quote the relevant code)
+- **Why it's a problem** (cite the guideline section or plan step)
+- **How to fix it** (concrete, actionable instruction — one sentence)
+
+#### Dimension 1 — Plan adherence
+
+- Does every file in the plan's **"Files to Create"** list exist?
+- Does every file in the plan's **"Files to Modify"** list show a diff?
+- Does the implementation match each **Implementation Step** described in the plan? (Structure, not line-by-line verbatim — intent counts.)
+- Are there files changed that are **not** in either list? (Flag as scope creep unless trivially justified.)
+
+#### Dimension 2 — Code guidelines compliance
+
+Check every changed file against `code-guidelines.md`, `project-structure.md`, and
+`mappers.md`. High-priority rules to verify:
+
+| Rule | Where to look |
+|---|---|
+{{> stack/review-checklist }}
+
+#### Dimension 3 — Context doc coverage
+
+Look at the plan's **"Context Docs to Update"** table. For each item:
+
+- **Create** action: does the file exist? Does it cover the sections the plan described?
+- **Update** action: does the diff show the file was modified in the way the plan described?
+
+If a context doc item is missing or incomplete, that is a blocking finding.
+
+#### Dimension 4 — Scope creep
+
+List any files modified that appear in the diff but are **not** in the plan's file lists. For each:
+- If the change is a necessary side-effect, mark it **expected** and move on.
+- If the change is not explained by the plan, flag it as **unexpected scope** — blocking if it introduces new behaviour, suggestion if it's a trivial cleanup.
+
+---
+
+## Report format
+
+Output the review as a structured markdown report. Use exactly this format:
+
+```
+## Code Review — [task] Step [step]
+
+### Summary
+[One paragraph: overall assessment. "No blocking issues found." or "X blocking issues, Y suggestions."]
+
+---
+
+### 🔴 Blocking Issues
+
+#### B1 — [Short title]
+**File:** `path/to/file.ts` (line N or function name)
+**Found:** [Quoted or paraphrased code]
+**Problem:** [Why it violates the guideline or plan — cite the source]
+**Fix:** [One-sentence instruction]
+
+#### B2 — ...
+
+---
+
+### 🟡 Suggestions
+
+#### S1 — [Short title]
+**File:** `path/to/file.ts`
+**Found:** [Quoted or paraphrased code]
+**Suggestion:** [What could be improved and why]
+
+---
+
+### ✅ Context Docs
+[One line per item from the plan's "Context Docs to Update" table: ✅ covered / ❌ missing / ⚠️ incomplete]
+
+### ✅ Plan Coverage
+[One line per "Files to Create/Modify": ✅ present / ❌ missing / ⚠️ differs from plan intent]
+
+### ⚠️ Scope Creep
+[List any unplanned file changes, or "None."]
+```
+
+If there are no blocking issues, say so clearly in the Summary. If there are no suggestions, omit that section entirely.
+
+---
+
+## When to stop and ask
+
+Stop and ask the user before producing the review if:
+
+- `plan-step-[step].md` does not exist — the developer may have run against the wrong step.
+- `description-step-[step].md` does not exist — the plan cannot be evaluated without understanding the original intent.
+- The git diff is empty for all plan-named files — the developer may not have committed or the task ID is wrong.
+
+---
+
+## What this agent does NOT do
+
+- Does not edit source files.
+- Does not re-run the developer agent.
+- Does not evaluate test coverage (out of scope for this project's current workflow).
+- Does not review files outside the diff (pre-existing issues in unchanged code are invisible to this agent).
+{{#if tracker.remote}}
+- **Does not sync to the tracker**, even on a clean review — moving to a done state is manual. See `ai/WORKFLOW.md` § Sync points.
+{{/if}}

package/presets/core/commands/_stub.md

@@ -0,0 +1,7 @@
+{{! cairn preset: core. The renderer emits one file per workflow.steps[] entry,
+    named `<step.command>.md`, into `.claude/commands/`. Every stub in
+    snap-proof/{backend,frontend} is byte-identical to this modulo the two
+    variables below (plus a stray BOM on the frontend copies). }}
+You are acting as **{{ step.agentName }}**. Read `{{ step.agentDoc }}` for your full role, workflow, and instructions.
+
+Run `{{ step.fn }}($ARGUMENTS)` — treat the first token as the task ID (e.g. {{ tracker.exampleKey }}-210) and the second as the step number (e.g. 1).

package/presets/core/workflow.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "cairn preset: core. The default workflow the renderer uses when a repo's cairn.config.json has no `workflow` block. Each step names its slash command, the underlying fn the agent docs refer to, and the role that runs it. `oneLine` is the AGENTS.md summary; `trackerAction` (optional) is the WORKFLOW.md sync-points cell for a remote tracker.",
+  "steps": [
+    {
+      "id": "brief",
+      "fn": "create_brief",
+      "command": "create-brief",
+      "role": "architect",
+      "oneLine": "creates the task brief scaffold for you to fill in",
+      "trackerAction": "create the parent issue if new; always create the child issue for this step; write its key into the brief frontmatter"
+    },
+    {
+      "id": "describe",
+      "fn": "enrich_description",
+      "command": "enrich-description",
+      "role": "architect",
+      "oneLine": "iterative discussion, then writes the enriched description",
+      "trackerAction": "child issue description ← the enriched description; a 1–2 sentence summary appended to the parent"
+    },
+    {
+      "id": "plan",
+      "fn": "plan_task",
+      "command": "plan-task",
+      "role": "architect",
+      "oneLine": "produces the implementation plan and any context-doc updates",
+      "trackerAction": "parent and child issue → in-progress stage"
+    },
+    {
+      "id": "execute",
+      "fn": "execute_plan",
+      "command": "execute-plan",
+      "role": "developer",
+      "oneLine": "implements the plan (switch to Haiku first)",
+      "trackerAction": "no sync"
+    },
+    {
+      "id": "review",
+      "fn": "code_review",
+      "command": "code-review",
+      "role": "reviewer",
+      "oneLine": "checks the result against the plan and the guidelines",
+      "trackerAction": "no sync — later stage moves are manual"
+    }
+  ]
+}

package/presets/drizzle/code-guidelines.md

@@ -0,0 +1,33 @@
+# Drizzle Guidelines
+
+<!-- cairn preset: drizzle. The ORM add-on for a Postgres/Supabase stack, parallel
+     to presets/typeorm. Seeded 2026-09-09 from charityiq-app (Sprint 0 — mostly
+     CLAUDE.md hard rules + ADR 0001, no battle-tested code yet). Single consumer:
+     refine when a second Drizzle repo appears. Composes onto a framework preset
+     (nestjs or react/nextjs) via `--stack <framework>,drizzle`. -->
+
+## Schema
+
+* One schema module — `lib/db/schema.ts`. Every table, column, and relation is declared there in Drizzle syntax.
+* Never write raw SQL in application code. The only place hand-written SQL is allowed is a migration file under `supabase/migrations/`.
+* Column names snake_case, TypeScript field names camelCase (Drizzle maps them).
+* Row-Level Security policies live in the migration files, not in the schema module — the schema describes shape, the migration describes access.
+
+## Migrations
+
+* Generate with `pnpm exec drizzle-kit generate` whenever the diff is mechanical; hand-write the `.sql` only for RLS policies, functions, triggers, and data backfills Drizzle Kit cannot express.
+* Review every generated migration before committing — check for accidental drops or type changes.
+* A schema change and its migration land in the same commit. The database is the source of truth; the schema module must always match what the migrations have applied.
+* Keep `ai/infrastructure/DATABASE_SCHEMA.md` current with each migration.
+
+## Clients
+
+* Server queries go through the `postgres-js` + Drizzle client in `lib/db/client.ts`. It uses the service-role key and must **never** be imported from a `"use client"` module.
+* The browser talks to the database only through the Supabase client, constrained by RLS — never the Drizzle client.
+
+## Queries
+
+* Prefer the typed query builder; reach for `sql` template literals only for expressions Drizzle does not model.
+* Select only the columns a caller needs.
+* Multi-step writes run inside `db.transaction(...)`.
+* Watch for N+1 — batch with `inArray` / a join rather than a loop of point reads.

package/presets/drizzle/slots/architect-discussion-topics.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: drizzle — appended to the framework preset's
+     architect-discussion-topics slot on `--stack <framework>,drizzle`. -->
+- **Schema shape** — new tables/columns, nullability, relations, indexes, RLS policy needed
+- **Migration scope** — mechanical `drizzle-kit generate` vs. a hand-written policy/backfill; is any change destructive

package/presets/drizzle/slots/architect-mandatory-docs.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: drizzle — appended to the framework preset's
+     architect-mandatory-docs slot on `--stack <framework>,drizzle`. -->
+- `ai/infrastructure/DATABASE_SCHEMA.md`
+- `lib/db/schema.ts` — the current Drizzle schema

package/presets/drizzle/slots/implementation-reference.md

@@ -0,0 +1,17 @@
+<!-- cairn preset: drizzle — appended to the framework preset's
+     implementation-reference slot on `--stack <framework>,drizzle`. -->
+
+### Schema
+- All tables in `lib/db/schema.ts`, Drizzle syntax; snake_case columns, camelCase fields
+- Relations declared with `relations(...)` so typed joins work
+- No RLS in the schema module — that goes in the migration
+
+### Migrations
+- `pnpm exec drizzle-kit generate` for mechanical diffs
+- Hand-write the `.sql` only for RLS policies, functions, triggers, backfills
+- One commit = schema edit + its migration
+
+### Access
+- Server: the Drizzle client in `lib/db/client.ts` (service-role, never in `"use client"`)
+- Browser: the Supabase client only, bounded by RLS
+- Reads select named columns; multi-step writes go in `db.transaction(...)`

package/presets/drizzle/slots/key-patterns.md

@@ -0,0 +1,7 @@
+<!-- cairn preset: drizzle — appended to the framework preset's key-patterns slot
+     on `--stack <framework>,drizzle`. -->
+
+Database schema: **`lib/db/schema.ts`** (single Drizzle module) and
+**`ai/infrastructure/DATABASE_SCHEMA.md`** — keep both current with every migration.
+
+Migration and RLS conventions: **`ai/infrastructure/code-guidelines.md`** § Drizzle.

package/presets/drizzle/slots/review-checklist.md

@@ -0,0 +1,10 @@
+<!-- cairn preset: drizzle — appended to the framework preset's review-checklist
+     slot on `--stack <framework>,drizzle`. -->
+
+| No raw SQL in application code — only the Drizzle query builder, or `sql` for expressions it can't model | any `.ts` outside `supabase/migrations/` |
+| Schema change committed together with its `drizzle-kit` migration | `lib/db/schema.ts` + `supabase/migrations/` |
+| Generated migration reviewed — no accidental drop or type change | the migration `.sql` |
+| RLS policy declared in a migration, not assumed | `supabase/migrations/` |
+| Server Drizzle client not imported from a `"use client"` module | client components |
+| Multi-step write wrapped in `db.transaction(...)` | service / action files |
+| `ai/infrastructure/DATABASE_SCHEMA.md` updated to match | that file |

package/presets/nestjs/code-guidelines.md

@@ -0,0 +1,273 @@
+# Code Guidelines
+
+<!-- cairn preset: nestjs. Composes with presets/typeorm for TypeORM-backed services. -->
+
+## General TypeScript Guidelines
+
+* Use TypeScript strict mode
+* Prefer `const` over `let`, never use `var`
+* Avoid using `any` type - use proper TypeScript types
+* Use async/await instead of raw promises
+* Handle all error cases explicitly
+* Use proper error types from NestJS (`NotFoundException`, `BadRequestException`, etc.)
+
+## NestJS Module Structure
+
+* Separate business logic (feature modules in `src/feature/`) from API layer (API modules in `src/api/modules/`)
+* Use proper dependency injection with `@Injectable()`, `@Module()` decorators
+* Register providers, imports, and exports correctly in module files
+* Keep controllers thin - delegate business logic to services
+
+## File Naming Conventions
+
+* Use kebab-case (dash-case) for all file names
+* Modules: `feature-name.module.ts`
+* Services: `feature-name.service.ts`
+* Controllers: `feature-name.controller.ts`
+* Entities: `feature-name.entity.ts`
+* Interfaces: `interface-name.interface.ts` (stored in `interfaces/` folder)
+* Tests: `feature-name.service.spec.ts`, `feature-name.controller.spec.ts`
+
+DTO file naming follows the validation stack:
+
+{{> slot: dto-naming }}
+
+## File Organization
+
+Every utility function, model, constant, DTO, or mapping function should be in a separated file.
+
+Files should be placed in appropriate folders within modules (see `ai/infrastructure/project-structure.md` for module details):
+
+* **constants/** - Constants specific to the module
+* **enums/** - Enums specific to the module
+* **interfaces/** - TypeScript interfaces (one per file)
+* **dtos/** - Data Transfer Objects for request/response
+* **entities/** - Database entities
+* **services/** - Business logic services
+* **controllers/** - HTTP controllers
+* **mappers/** - Mapping functions for transforming data
+
+## Interfaces
+
+**IMPORTANT**: Store interfaces separately from code in dedicated interface files.
+
+**Rules**:
+* Each interface gets its own file in `src/feature/[feature-name]/interfaces/` folder
+* File naming: convert interface name to kebab-case + `.interface.ts`
+  - E.g., `CreateUserData` → `create-user-data.interface.ts`
+  - E.g., `RegisterOwnerResult` → `register-owner-result.interface.ts`
+* One interface per file — no mixing multiple interfaces
+* Interfaces are NOT exported from barrel files unless necessary
+
+**Examples**:
+```typescript
+// src/feature/user/interfaces/create-user-data.interface.ts
+export interface CreateUserData {
+  companyId: string;
+  email: string;
+  name: string;
+  passwordHash: string;
+  role?: TenantRole;
+}
+
+// src/feature/user/interfaces/register-owner-result.interface.ts
+export interface RegisterOwnerResult {
+  user: User;
+  company: Company;
+}
+```
+
+## Controllers
+
+* Keep controllers thin - only handle HTTP concerns
+* Use proper HTTP method decorators: `@Get()`, `@Post()`, `@Put()`, `@Delete()`, `@Patch()`
+* Use parameter decorators: `@Body()`, `@Param()`, `@Query()`, `@Headers()`
+* Use `@UseGuards()` for authentication and authorization
+* Return consistent response structures
+* Let NestJS exception filters handle errors
+
+Response typing and serialization are stack-specific:
+
+{{> slot: controller-response }}
+
+## Services
+
+* Implement all business logic in services
+* Use dependency injection for all dependencies
+* Mark services with `@Injectable()` decorator
+* Handle database transactions properly
+* Throw appropriate NestJS exceptions
+* Keep methods focused and single-purpose
+* Use async/await for all asynchronous operations
+
+## DTOs (Data Transfer Objects)
+
+* Create separate DTOs for different operations:
+    - `create-*.dto.ts` for POST requests
+    - `update-*.dto.ts` for PUT/PATCH requests
+    - `*-response.dto.ts` for responses
+    - `*-query.dto.ts` for query parameters
+
+{{> slot: dto-definition }}
+
+## Validation
+
+* Validate at API boundaries (in controllers via DTOs)
+* Provide clear, user-friendly validation error messages
+
+{{> slot: validation-stack }}
+
+## Error Handling
+
+* Use NestJS built-in exceptions:
+    - `NotFoundException` - Resource not found (404)
+    - `BadRequestException` - Invalid input (400)
+    - `UnauthorizedException` - Not authenticated (401)
+    - `ForbiddenException` - Not authorized (403)
+    - `ConflictException` - Resource conflict (409)
+* Create custom exception classes for domain-specific errors
+* Use exception filters for global error handling
+* Log errors appropriately (use NestJS Logger)
+* Never expose sensitive information in error messages
+* Never expose stack traces in production
+
+## Error Codes
+
+**MANDATORY**: Every thrown exception **must** include a machine-readable `code` from `ERROR_CODES`.
+
+**Why**: Frontend uses `code` to display localized messages. String-matching on `message` is forbidden.
+
+**Constants file**: `src/common/constants/error-codes.constant.ts` — single source of truth for all codes.
+Add new codes here before using them. Never use inline strings.
+
+**Throw pattern**:
+```typescript
+// Correct
+import { ERROR_CODES } from '@common/constants/error-codes.constant';
+throw new NotFoundException({ message: 'User not found', code: ERROR_CODES.USER_NOT_FOUND });
+
+// Incorrect — missing code
+throw new NotFoundException('User not found');
+```
+
+**Naming convention**: `SCREAMING_SNAKE_CASE`, format `[DOMAIN]_[REASON]`
+- `USER_NOT_FOUND`, `USER_DEACTIVATED`
+- `INVITATION_NOT_FOUND`, `USER_LIMIT_REACHED`
+- `INVALID_CREDENTIALS`, `CONFIRMATION_TOKEN_EXPIRED`
+
+**Exceptions to this rule** (do NOT add codes):
+- Validation pipe errors — these carry a per-field `code` in the `errors` array instead
+- Bare `UnauthorizedException()` in the JWT strategy — no info leak on invalid token by design
+
+## Response Transformation
+
+{{> slot: response-transformation }}
+
+## Pagination
+
+Use a shared `paginatedResponseSchema` helper for all list endpoints that return paginated data.
+
+**Rules**:
+* Query params always use `page`/`pageSize` — never expose `skip`/`take` to the client
+* Response always uses the `{ items, total, skip, take }` shape — never `page`/`pageSize`
+* `pageSize` max is 100; default is 50
+* Always use `getManyAndCount()` so `total` is accurate
+
+**Service** — convert `page`/`pageSize` to `skip`/`take` and return the envelope:
+
+```typescript
+async list(params: { page: number; pageSize: number }): Promise<{ items: Foo[]; total: number; skip: number; take: number }> {
+  const skip = (params.page - 1) * params.pageSize;
+  const take = params.pageSize;
+  const [items, total] = await qb.skip(skip).take(take).getManyAndCount();
+  return { items, total, skip, take };
+}
+```
+
+Query-param coercion and response-DTO declaration are stack-specific:
+
+{{> slot: pagination-dtos }}
+
+## Security
+
+* Sanitize all user input
+* Use parameterized queries (the ORM handles this automatically)
+* Implement authentication with Guards (`@UseGuards(AuthGuard)`)
+* Implement authorization checks for protected resources
+* Validate file uploads (type, size, content)
+* Never commit secrets, API keys, or credentials to version control
+* Use environment variables for configuration
+* Hash passwords with bcrypt
+* Use HTTPS in production
+
+## Constants
+
+File name template: `xx-yy.constant.ts` for `XxYy` constant
+
+Files with constants should be placed in the `constants/` folder within the corresponding module (see
+`ai/infrastructure/project-structure.md` for module details)
+
+## Enums
+
+File name template: `xx-yy.enum.ts` for `XxYy` enum
+
+Files with enums should be placed in the `enums/` folder within the corresponding module (see `ai/infrastructure/project-structure.md` for
+module details)
+
+## No Magic Strings or Numbers
+
+**MANDATORY**: Never use raw string or number literals where a named constant or enum value can be used instead. Magic values scatter meaning across the codebase, make refactoring error-prone, and produce silent bugs when a value changes in one place but not another.
+
+**Rules**:
+* Any string or number that carries domain meaning and appears in more than one place **must** be a constant or enum
+* Any string or number that carries domain meaning and appears in only one place **should still** be a constant or enum if it is likely to be referenced elsewhere in the future (e.g. audit action names, entity type labels, JWT token types)
+* Raw string comparisons against domain values are always wrong — use the enum
+
+**Enums** for closed sets of values (token types, roles, statuses, entity types, action names):
+```typescript
+// ✅ Correct
+export enum JwtType {
+  USER = 'user',
+  ADMIN = 'admin',
+  IMPERSONATION = 'impersonation',
+}
+
+if (payload.type === JwtType.IMPERSONATION) { ... }
+
+// ❌ Incorrect
+if (payload.type === 'impersonation') { ... }
+```
+
+**Constants** for single values with no closed set (limits, expiry defaults, config keys):
+```typescript
+// ✅ Correct — src/feature/user/constants/max-invitation-attempts.constant.ts
+export const MAX_INVITATION_ATTEMPTS = 5;
+
+// ❌ Incorrect
+if (attempts > 5) { ... }
+```
+
+**Where to place them**:
+* Enums belong in `enums/` within the owning module — see **Enums** section above
+* Constants belong in `constants/` within the owning module — see **Constants** section above
+* Cross-cutting enums/constants (e.g. `JwtType`, `ERROR_CODES`) belong in `src/common/`
+
+**Common categories that always require an enum or constant**:
+* JWT `type` field values
+* Audit action names and entity type labels
+* Platform and tenant role values
+* Any status value with a closed set
+* Any HTTP header name, cookie name, or metadata key used in multiple places
+
+## Code Quality
+
+* Follow SOLID principles
+* Keep functions small and focused (single responsibility)
+* Use meaningful variable and function names
+* Add comments only where logic is complex or non-obvious
+* Remove commented-out code before committing
+* Use TypeScript features: interfaces, types, generics, decorators
+* Prefer composition over inheritance
+* Use dependency injection for loose coupling
+* Write self-documenting code
+* Keep code DRY (Don't Repeat Yourself)

package/presets/nestjs/slots/architect-discussion-topics.md

@@ -0,0 +1,4 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-discussion-topics }} (A.3).
+     `--stack nestjs,typeorm` also appends the typeorm slot (schema, migrations). -->
+- **API design questions** — endpoint naming, request/response shape, pagination or filtering needs
+- **Layering** — what belongs in the feature module vs. the API module

package/presets/nestjs/slots/architect-mandatory-docs.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-mandatory-docs }} (A.2).
+     `--stack nestjs,typeorm` also appends the typeorm slot (DATABASE_SCHEMA.md). -->
+- `ai/infrastructure/code-guidelines.md`
+- `ai/infrastructure/project-structure.md`
+- `ai/infrastructure/mappers.md`

package/presets/nestjs/slots/architect-references.md

@@ -0,0 +1,5 @@
+<!-- cairn preset: nestjs — fills {{> stack/architect-references }} (A.1).
+     Primary-stack-only, not concatenated. -->
+- Backend source files (modules, services, entities, DTOs, controllers)
+- Context docs in `ai/contexts/**` — entity definitions, business logic, feature docs
+- The frontend repo's context docs, if the task touches an API shape the frontend consumes

package/presets/nestjs/slots/implementation-reference.md

@@ -0,0 +1,45 @@
+<!-- cairn preset: nestjs — fills {{> stack/implementation-reference }} in the core
+     developer. Framework areas only. `--stack nestjs,typeorm` also appends
+     presets/typeorm/slots/implementation-reference.md (entities, migrations,
+     repositories). From snap-proof/backend/ai/agents/node-developer.md. -->
+
+Quick reminders for the most common implementation areas. The authoritative source
+is always `ai/infrastructure/code-guidelines.md`.
+
+### Module structure
+- Feature modules in `src/feature/<name>/` — business logic and services
+- API modules in `src/api/modules/<name>/` — HTTP layer only (controllers, API-layer services, request/response DTOs)
+- Register providers, imports, and exports explicitly in every module file
+
+### Controllers
+- Thin controllers: delegate all business logic to services
+- `@Get()` / `@Post()` / `@Put()` / `@Patch()` / `@Delete()` with explicit route paths
+- Bind inputs with `@Body()`, `@Param()`, `@Query()`
+- Apply `@UsePipes(ValidationPipe)` and `@UseGuards()` where required
+- Return consistent response shapes; use response DTOs and mappers
+
+### Services
+- All business logic in feature services; API-layer services handle HTTP concerns only
+- Throw NestJS built-in exceptions: `NotFoundException`, `BadRequestException`, `UnauthorizedException`, …
+- async/await throughout
+
+### DTOs
+- One file per DTO, `.dto.ts` suffix; validation decorators for every property (per the validation-stack variant)
+- `@ApiProperty()` from `@nestjs/swagger` on every property
+- Request DTOs in `src/api/dtos/`; shared/internal DTOs in `src/feature/dtos/`
+
+### Error handling
+- Use NestJS exceptions — never expose raw DB errors or stack traces
+- Custom exceptions extend `HttpException` only when no built-in fits
+- Log errors at service level; never log sensitive data
+
+### Testing
+- Unit tests for services: `feature-name.service.spec.ts`
+- `Test.createTestingModule()` for NestJS context; mock dependencies
+- Cover happy paths, not-found cases, and validation failures
+
+### File naming
+- `feature-name.module.ts` / `.service.ts` / `.controller.ts`
+- DTOs: `create-feature.dto.ts`, `update-feature.dto.ts`, `feature-response.dto.ts`
+- Tests: `feature-name.service.spec.ts`
+- All kebab-case

package/presets/nestjs/slots/key-patterns.md

@@ -0,0 +1,11 @@
+<!-- cairn preset: nestjs — fills {{> stack/key-patterns }} in the core architect
+     and developer. `--stack nestjs,typeorm` also appends the typeorm slot. -->
+
+Module and layer conventions: **`ai/infrastructure/project-structure.md`** — feature
+modules (`src/feature/`) vs. API modules (`src/api/modules/`), service/repository
+placement. Plans should follow the same shape.
+
+Code conventions (naming, DTOs, validation, decorators, error handling):
+**`ai/infrastructure/code-guidelines.md`**.
+
+Mapper conventions: **`ai/infrastructure/mappers.md`**.

package/presets/nestjs/slots/plan-step-ordering.md

@@ -0,0 +1,12 @@
+<!-- cairn preset: nestjs — fills {{> stack/plan-step-ordering }} in the core
+     architect's Plan format. This slot is *not* concatenated across stack entries
+     — it is one coherent sequence, taken from the primary stack (stack[0]). It
+     assumes an ORM in step 1; a bare `--stack nestjs` repo trims that step.
+     From node-architect.md. -->
+1. Entity / migration changes
+2. Feature module — service and repository setup
+3. DTOs and validation decorators
+4. API module — controller and endpoint implementation
+5. Error handling and edge cases
+6. Unit and integration test hooks
+7. Context doc updates