coding-os 0.3.2__py3-none-any.whl

templates/nextjs/stack.yaml

@@ -0,0 +1,81 @@
+version: 1
+id: nextjs
+language: typescript
+label: "Next.js + React + TypeScript"
+category: frontend
+
+structure:
+  root: src/frontend
+  tree: |
+    src/frontend/
+    ├── app/             # app-router pages + layouts
+    ├── components/
+    └── lib/
+  notes: "app-router convention; design tokens under docs/design/"
+primary_skill: nextjs-react
+skills: [nextjs-react]
+
+# These substitution keys are joined across stacks by the aggregator.
+# VERIFY_FRONTEND_* override the "(none)" defaults from base.yaml.
+substitutions:
+  DOMAIN_ROUTES: "Frontend→`docs/playbooks/frontend-ui.md`, Content→`docs/playbooks/content-seo.md`"
+  SKILL_ROUTES: "Frontend→`nextjs-react`"
+  ENGINEERING_RULE_ROUTING: "Frontend→`docs/engineering/frontend-rules.md`, Rendering→`docs/engineering/frontend-rendering-rules.md`, Copy→`docs/engineering/copywriting-standard.md`, i18n→`docs/engineering/i18n-policy.md`, a11y→`docs/engineering/accessibility-web.md`, Format→`docs/engineering/formatting-rules.md`"
+  TOOL_ROUTING_IMPL: "`lint-frontend`, `test-frontend`, `build-frontend`"
+  VERIFY_FRONTEND_GLOB: "`src/frontend/`"
+  VERIFY_FRONTEND_SUITES: "lint-frontend + test-frontend"
+  VERIFY_FRONTEND: "`cd src/frontend && npm run lint && npm test`"
+  QUICK_ROUTING: |-
+    - UI / component task → [Frontend UI Playbook](./playbooks/frontend-ui.md)
+    - Content / SEO / metadata task → [Content & SEO Playbook](./playbooks/content-seo.md)
+    - Docs / workflow / AGENTS task → [Docs Governance Playbook](./playbooks/docs-governance.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-FRONTEND` → `./playbooks/frontend-ui.md`
+    - `REF:PLAYBOOK-CONTENT` → `./playbooks/content-seo.md`
+    - `REF:PLAYBOOK-DOCS-GOV` → `./playbooks/docs-governance.md`
+    - `REF:FRONTEND-RULES` → `./engineering/frontend-rules.md`
+    - `REF:FRONTEND-RENDER` → `./engineering/frontend-rendering-rules.md`
+    - `REF:I18N-POLICY` → `./engineering/i18n-policy.md`
+    - `REF:COPYWRITING` → `./engineering/copywriting-standard.md`
+    - `REF:A11Y` → `./engineering/accessibility-web.md`
+    - `REF:DESIGN-INDEX` → `./design/00-index.md`
+    - `REF:CONTENT-INDEX` → `./pages-content-spec/00-index.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-FRONTEND", path: "./playbooks/frontend-ui.md",            desc: "Frontend UI playbook"}
+  - {code: "REF:PLAYBOOK-CONTENT",  path: "./playbooks/content-seo.md",            desc: "Content & SEO playbook"}
+  - {code: "REF:PLAYBOOK-DOCS-GOV", path: "./playbooks/docs-governance.md",        desc: "Docs governance playbook"}
+  - {code: "REF:FRONTEND-RULES",    path: "./engineering/frontend-rules.md",       desc: "Frontend rules"}
+  - {code: "REF:FRONTEND-RENDER",   path: "./engineering/frontend-rendering-rules.md", desc: "Frontend rendering rules"}
+  - {code: "REF:I18N-POLICY",       path: "./engineering/i18n-policy.md",          desc: "i18n policy"}
+  - {code: "REF:COPYWRITING",       path: "./engineering/copywriting-standard.md", desc: "Copywriting standard"}
+  - {code: "REF:A11Y",              path: "./engineering/accessibility-web.md", desc: "Accessibility checklist"}
+  - {code: "REF:DESIGN-INDEX",      path: "./design/00-index.md",                  desc: "Design index"}
+  - {code: "REF:CONTENT-INDEX",     path: "./pages-content-spec/00-index.md",      desc: "Content spec index"}
+
+routing_entries:
+  - "UI / component task → [Frontend UI Playbook](./playbooks/frontend-ui.md)"
+  - "Content / SEO / metadata task → [Content & SEO Playbook](./playbooks/content-seo.md)"
+  - "Docs / workflow / AGENTS task → [Docs Governance Playbook](./playbooks/docs-governance.md)"
+
+rules:
+  - {file: rules/frontend.md, globs: ["src/frontend/**/*.{ts,tsx,css}"]}
+
+dimensions:
+  - {name: "React component",   read_files: ["docs/engineering/frontend-rules.md", "docs/playbooks/frontend-ui.md"]}
+  - {name: "Page / route",      read_files: ["docs/engineering/frontend-rendering-rules.md", "docs/playbooks/frontend-ui.md"]}
+  - {name: "Content / SEO",     read_files: ["docs/playbooks/content-seo.md", "docs/engineering/copywriting-standard.md"]}
+  - {name: "i18n",              read_files: ["docs/engineering/i18n-policy.md"]}
+  - {name: "Accessibility",     read_files: ["docs/engineering/accessibility-web.md"]}
+
+skill_enforcement:
+  - {globs: ["src/frontend/**/*.{ts,tsx}"], primary: nextjs-react, secondary: [clean-code, frontend-design, frontend-fundamentals, a11y, performance, testing-strategy]}
+  - {globs: ["src/frontend/**/components/**/*.{ts,tsx}", "src/frontend/**/app/**/page.tsx", "src/frontend/**/app/**/layout.tsx"], primary: nextjs-react, secondary: [clean-code, frontend-design, frontend-fundamentals, a11y]}
+  - {globs: ["src/frontend/**/store/**/*.ts", "src/frontend/**/stores/**/*.ts", "src/frontend/**/hooks/use*.ts"], primary: nextjs-react, secondary: [state-management, clean-code, frontend-fundamentals]}
+
+makefile_targets:
+  - {name: lint-frontend, cmd: "cd src/frontend && npm run lint"}
+  - {name: test-frontend, cmd: "cd src/frontend && npm test"}
+
+verify:
+  - {glob: "src/frontend/**/*.{ts,tsx}", suites: "lint-frontend + test-frontend", cmd: "cd src/frontend && npm run lint && npm test"}

templates/node-express/rules/backend.md

@@ -0,0 +1,20 @@
+---
+globs: ["src/backend/**/*.ts"]
+alwaysApply: false
+---
+
+# Express Backend Rules (auto-loaded on src/backend/**/*.ts)
+
+When editing any TypeScript file under `src/backend/` in an Express project, follow these standards:
+
+- **Layering** — routes → services → repositories; imports flow one way only (the table in the `node-express` skill is the SSOT).
+- **Async safety** — every async handler is wrapped; an unhandled rejection in a route is a build-blocking review finding.
+- **One error shaper** — only `middleware/error-handler.ts` writes error bodies; it logs full detail and returns the problem shape with no internals (no stack traces, no driver messages).
+- **Validation fail-closed** — unvalidated `req.body` never crosses into a service; reject with 400 + problem shape on schema mismatch.
+- **Strict TypeScript** — `tsc --noEmit` is the lint gate; `any` requires a written justification at the cast site.
+- **No floating config** — environment access happens once at bootstrap; services receive typed config, never read `process.env`.
+- **Testing bar** — services unit-tested per public method; routes covered happy + error path via supertest; repositories integration-tested against a disposable database.
+
+Canonical policy: `docs/engineering/express-rules.md`
+Playbook: `docs/playbooks/express-service.md`
+Primary skill: `node-express`

templates/node-express/scaffold/docs/engineering/express-rules.md

@@ -0,0 +1,30 @@
+<!-- domain:BACKEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Express Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Express backend.
+Read when: Editing anything under `src/backend/`.
+Skip when: Frontend/mobile work.
+Read next: [Express Service Playbook](../playbooks/express-service.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Layering** — routes → services → repositories, imports flow one way only
+   (the table in the `node-express` skill is the SSOT).
+2. **Async safety** — every async handler is wrapped; an unhandled rejection
+   in a route is a build-blocking review finding.
+3. **One error shaper** — only `middleware/error-handler.ts` writes error
+   bodies; it logs full detail and returns the problem shape with no
+   internals (no stack traces, no driver messages).
+4. **Validation fail-closed** — unvalidated `req.body` never crosses into a
+   service; reject with 400 + problem shape on schema mismatch.
+5. **Strict TypeScript** — `tsc --noEmit` is the lint gate; `any` requires a
+   written justification at the cast site.
+6. **No floating config** — environment access happens once at bootstrap;
+   services receive typed config, never read `process.env`.
+
+## Testing bar
+
+Services ≥ unit-tested per public method; routes ≥ happy + error path via
+supertest; repositories integration-tested against a disposable database.

templates/node-express/scaffold/docs/playbooks/express-service.md

@@ -0,0 +1,35 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Express Service Playbook
+
+Purpose: The end-to-end recipe for adding or changing an Express endpoint in {{PROJECT_NAME}}.
+Read when: Any task that adds a route, middleware, service method, or repository.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [Express Engineering Rules](../engineering/express-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add an endpoint (the only sanctioned path)
+
+1. **Contract first** — define request/response shapes; error cases use the
+   shared problem format ([error-format](../api-contracts/error-format.md)).
+2. **Route** — `src/backend/src/routes/<resource>.ts`: validate input at the
+   boundary, call exactly one service method, map the result to a response.
+   Async handlers go through the `asyncHandler` wrapper.
+3. **Service** — `src/services/<resource>-service.ts`: business logic only,
+   no `Request`/`Response` types, typed domain errors on failure.
+4. **Repository** — data access for one aggregate; services never touch the
+   DB client directly.
+5. **Wire** — mount the router in `src/index.ts` BEFORE the error handler.
+6. **Test** — unit-test the service (no HTTP) + supertest the route via
+   `createApp()` (one happy path, one error path, minimum).
+7. **Verify** — `cd src/backend && npm run lint && npm test`.
+
+## Middleware order (registration = dispatch order)
+
+`json body parser → request-id/logging → auth → routers → 404 → error handler (last)`
+
+## Anti-patterns
+
+- Error JSON built inside a route — the central handler owns the shape.
+- A service importing express types — that layer must stay framework-free.
+- `app.listen` inside tests — always test through the `createApp()` factory.

templates/node-express/scaffold/src/backend/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "{{PROJECT_NAME}}-backend",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=21"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "lint": "tsc --noEmit",
+    "test": "node --import tsx --test \"src/**/*.test.ts\""
+  },
+  "dependencies": {
+    "express": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/supertest": "^6.0.2",
+    "supertest": "^7.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  }
+}

templates/node-express/scaffold/src/backend/src/index.ts

@@ -0,0 +1,17 @@
+import express from "express";
+
+import { healthRouter } from "./routes/health.js";
+import { errorHandler } from "./middleware/error-handler.js";
+
+export function createApp() {
+  const app = express();
+  app.use(express.json());
+  app.use("/health", healthRouter);
+  app.use(errorHandler); // MUST stay last — Express dispatches in registration order
+  return app;
+}
+
+const port = Number(process.env.PORT ?? 3000);
+createApp().listen(port, () => {
+  console.log(`{{PROJECT_NAME}} backend listening on :${port}`);
+});

templates/node-express/scaffold/src/backend/src/middleware/error-handler.ts

@@ -0,0 +1,12 @@
+import type { NextFunction, Request, Response } from "express";
+
+// The ONLY place that shapes error responses (docs/api-contracts/error-format.md).
+export function errorHandler(
+  err: unknown,
+  _req: Request,
+  res: Response,
+  _next: NextFunction,
+): void {
+  console.error(err); // full detail to the log, never to the client
+  res.status(500).json({ title: "Internal Server Error", status: 500 });
+}

templates/node-express/scaffold/src/backend/src/routes/health.test.ts

@@ -0,0 +1,33 @@
+// Sample route test for {{PROJECT_NAME}} ({{DATE}}) — exercises the shipped
+// healthRouter via supertest in-memory, never binding a real port
+// (docs/playbooks/express-service.md: test through the factory, no app.listen).
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import express from "express";
+import request from "supertest";
+
+import { healthRouter } from "./health.js";
+
+// Mirror index.ts's createApp() mount, minus the listen() side effect, so the
+// test drives the SAME router the running service mounts at /health.
+function buildTestApp() {
+  const app = express();
+  app.use(express.json());
+  app.use("/health", healthRouter);
+  return app;
+}
+
+test("GET /health returns 200 with status ok", async () => {
+  const res = await request(buildTestApp()).get("/health");
+
+  assert.equal(res.status, 200);
+  assert.deepEqual(res.body, { status: "ok" });
+});
+
+test("unknown method on /health is not served by the router (404)", async () => {
+  // The health router only registers GET "/"; a DELETE falls through unhandled.
+  const res = await request(buildTestApp()).delete("/health");
+
+  assert.equal(res.status, 404);
+});

templates/node-express/scaffold/src/backend/src/routes/health.ts

@@ -0,0 +1,7 @@
+import express from "express";
+
+export const healthRouter = express.Router();
+
+healthRouter.get("/", (_req, res) => {
+  res.status(200).json({ status: "ok" });
+});

templates/node-express/scaffold/src/backend/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": []
+  },
+  "include": ["src", "types"],
+  "exclude": ["**/*.test.ts"]
+}

templates/node-express/scaffold/src/backend/types/express-bootstrap.d.ts

@@ -0,0 +1,21 @@
+// Pre-install ambient stub so `npm run lint` (tsc --noEmit) passes on a fresh
+// scaffold BEFORE `npm install` pulls @types/express. Real typings shadow this
+// file automatically once node_modules exists — do not extend it.
+declare module "express" {
+  export interface Request { params: Record<string, string>; body: unknown }
+  export interface Response { status(code: number): Response; json(body: unknown): Response }
+  export type NextFunction = (err?: unknown) => void
+  export type RequestHandler = (req: Request, res: Response, next: NextFunction) => unknown
+  export interface Router {
+    get(path: string, ...handlers: RequestHandler[]): Router
+    use(...handlers: unknown[]): Router
+  }
+  export interface Application extends Router { listen(port: number, cb?: () => void): unknown }
+  interface ExpressFactory { (): Application; Router(): Router; json(): RequestHandler }
+  const express: ExpressFactory
+  export default express
+}
+
+// Node globals used by the bootstrap, pre-install (real @types/node shadows this).
+declare const process: { env: Record<string, string | undefined> };
+declare const console: { log(...args: unknown[]): void; error(...args: unknown[]): void };

templates/node-express/scaffold-boundary.yaml

@@ -0,0 +1,25 @@
+# Scaffold boundary for the node-express stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: node-express
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.ts"
+  - "src/backend/**/*.json"
+
+imports_from:
+  - src/shared/
+  - src/shared/types/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Routes thin; services own logic; repositories own data access."
+  - "Central error middleware is the only error-response shaper."

templates/node-express/skills/node-express/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: node-express
+tier: stack
+domain: [backend]
+description: Use when creating or modifying TypeScript files under src/backend/ in an Express service — routers, middleware, services, repositories, and their tests. Triggers on any .ts change under src/backend/. Covers router organization, middleware ordering, the central error handler, async handler wrapping, and request validation. Node.js fundamentals live in the core node-backend skill.
+globs: "src/backend/**/*.ts"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+  - node-backend
+last_reviewed: "2026-06-11"
+---
+
+REQUIRED BACKGROUND: You MUST also follow the core `node-backend` skill (Node runtime, event loop, packaging) and `clean-code`. This skill adds Express-specific patterns on top.
+
+# node-express
+
+## Layer contract (matches `structure.tree`)
+
+| Layer | May import | Never |
+|---|---|---|
+| `routes/` | services, middleware | repositories, other routers |
+| `middleware/` | services (auth lookups) | repositories |
+| `services/` | repositories, other services | express types (`Request`/`Response`) |
+| `repositories/` | the DB client | services, express |
+
+Services stay framework-free — that is what makes them unit-testable and what
+keeps a future framework swap (Fastify, Hono) a routes-layer-only change.
+
+## Router organization
+
+- One router file per resource (`routes/users.ts` exports `usersRouter`).
+- Handlers are thin: parse/validate → call ONE service method → shape response.
+- Mount order in `index.ts`: body parsers → request-id/logging → auth →
+  routers → 404 → **error handler last** (Express dispatches by registration
+  order; a handler registered after the error middleware is unreachable).
+
+## Async handlers
+
+Express 4 does not catch rejected promises. Every async handler goes through
+the wrap helper so rejections reach the central error handler instead of
+crashing the process:
+
+```ts
+export const asyncHandler =
+  (fn: RequestHandler): RequestHandler =>
+  (req, res, next) => Promise.resolve(fn(req, res, next)).catch(next);
+```
+
+## Error handling
+
+- ONE central error middleware shapes every error response (RFC 9457 problem
+  shape per `docs/api-contracts/error-format.md`). Routes never build error
+  JSON ad-hoc.
+- Typed domain errors (`NotFoundError`, `ValidationError`) map to statuses in
+  that one place; unknown errors → 500 with a generic message, full detail to
+  the logger only (no stack traces to clients).
+
+## Validation
+
+Validate at the boundary (router) with a schema (zod or similar), reject
+fail-closed, and hand the service a TYPED value — services never read `req`.
+
+## Testing
+
+- Services: pure unit tests, no HTTP.
+- Routes: supertest against the app factory, one happy + one error-path test
+  per endpoint minimum.
+- The app is built by an exported `createApp()` factory so tests never bind a
+  real port.

templates/node-express/skills/node-express/references/anatomy.md

@@ -0,0 +1,63 @@
+<!-- domain:NODEEXPRESS | layer:reference | ssot:true | updated:2026-06-27 -->
+# Express Anatomy
+
+> P: Canonical file map + entity recipes for the Node + Express (layered, TypeScript) stack.
+> R: Adding any `.ts` under `src/backend/`, or routing a backend task.
+> S: Reading frontend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/node-express/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Router | `src/routes/<resource>.ts` | `<resource>.ts` | its service | One router per resource; thin handlers |
+| Service | `src/services/<name>.ts` | `<name>.ts` | repository | Business logic (the only layer that thinks) |
+| Repository | `src/repositories/<name>.ts` | `<name>.ts` | db client | Data access, one per aggregate |
+| Middleware | `src/middleware/<name>.ts` | `<name>.ts` | none | Auth, validation, central error handler |
+| Bootstrap | `src/index.ts` | `index.ts` | routes, middleware | App wiring — no logic |
+| Test | `<file>.test.ts` | `<file>.test.ts` | source under test | Vitest / Jest + supertest |
+
+## 3. Entity recipes
+
+### Add a new endpoint
+- **Trigger:** "add `POST /<resource>`".
+- **Files emitted:**
+  1. `src/routes/<resource>.ts`
+  2. `src/services/<resource>.ts`
+- **Steps:**
+  1. Validate the body in middleware; the handler delegates to the service.
+  2. Throw typed errors; the central error handler (last middleware) shapes them.
+  3. Mount the router in `src/index.ts`.
+
+### Add a new model
+- **Trigger:** "persist `<Entity>`".
+- **Files emitted:** `src/repositories/<name>.ts`.
+- **Steps:**
+  1. Repository owns the query; never a query in a service or handler.
+
+### Add a new test
+- **Trigger:** any new endpoint / service.
+- **Files emitted:** `<file>.test.ts` next to source.
+- **Steps:**
+  1. `supertest` for routes (happy + error); mock the repo for service tests.
+
+## 4. Conventions
+
+#### Naming
+- Files: `kebab-case.ts`. Functions: `camelCase`; types: `PascalCase`.
+
+#### Test colocation
+- Colocated: `<file>.test.ts` next to source.
+
+#### Dependency rules
+- ✓ router → service → repository.
+- ✗ no business logic in middleware; error responses only from the central handler.
+- ✗ `src/backend/` never imports from `src/frontend/` / `src/mobile/` — share via `src/shared/`.

templates/node-express/stack.yaml

@@ -0,0 +1,63 @@
+version: 1
+id: node-express
+language: typescript
+label: "Node.js + Express + TypeScript"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── package.json
+    ├── tsconfig.json
+    └── src/
+        ├── index.ts         # app bootstrap (no logic)
+        ├── routes/          # one router per resource, thin handlers
+        ├── middleware/      # auth, validation, error handler (order matters)
+        ├── services/        # business logic — the only layer that thinks
+        └── repositories/    # data access, one per aggregate
+  notes: "routes thin, services own logic; central error handler is the ONLY place that shapes error responses"
+primary_skill: node-express
+skills: [node-express]
+
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/express-service.md`"
+  SKILL_ROUTES: "Backend→`node-express`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/express-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && npm run lint && npm test`"
+  QUICK_ROUTING: |-
+    - Express route / middleware task → [Express Service Playbook](./playbooks/express-service.md)
+    - Auth / validation middleware → [Express Service Playbook](./playbooks/express-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-EXPRESS` → `./playbooks/express-service.md`
+    - `REF:EXPRESS-RULES` → `./engineering/express-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-EXPRESS", path: "./playbooks/express-service.md", desc: "Express service playbook"}
+  - {code: "REF:EXPRESS-RULES",    path: "./engineering/express-rules.md", desc: "Express engineering rules"}
+
+routing_entries:
+  - "Express route / middleware task → [Express Service Playbook](./playbooks/express-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.ts"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && npm run lint"}
+  - {name: test-backend, cmd: "cd src/backend && npm test"}
+
+verify:
+  - {glob: "src/backend/**/*.ts", suites: "lint-backend + test-backend", cmd: "cd src/backend && npm run lint && npm test"}
+
+dimensions:
+  - {name: "Express route",       read_files: ["docs/playbooks/express-service.md", "docs/engineering/express-rules.md"]}
+  - {name: "Middleware / auth",   read_files: ["docs/engineering/express-rules.md"]}
+  - {name: "Request validation / DTO", read_files: ["docs/engineering/express-rules.md", "docs/api-contracts/error-format.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.ts"], primary: node-express, secondary: [clean-code, backend-fundamentals, api-design, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/repositories/**/*.ts", "src/backend/**/db/**/*.ts"], primary: node-express, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/middleware/auth*.ts", "src/backend/**/auth*.ts"], primary: node-express, secondary: [auth-patterns, security-web, clean-code]}

templates/python/scaffold/docs/engineering/python-rules.md

@@ -0,0 +1,27 @@
+# Python Engineering Rules
+
+Project: {{PROJECT_NAME}} · Updated: {{DATE}}
+
+## Layout
+
+- **Package code** in `src/<package>/` (src-layout) — keeps imports honest in tests.
+- **Tests** in `tests/`, mirroring the package tree; fixtures in `tests/conftest.py`.
+- **Packaging SSOT** is `pyproject.toml` — version, deps, entry points; no `setup.py`.
+
+## Style & safety
+
+- Type hints on every public signature; `from __future__ import annotations` in new modules.
+- Fail closed: raise typed, domain-specific exceptions; never return silent fallbacks.
+- No bare `except Exception` without a debug log; fire-and-forget helpers log and continue.
+- Resolve paths with `pathlib.Path` and `.resolve()` before `relative_to()` (macOS /tmp quirk).
+- Magic numbers/strings become named constants at module top.
+
+## Dependencies
+
+- Add runtime deps to `pyproject.toml` with a floor pin (`>=`); dev-only deps to the dev extra.
+- Prefer the stdlib; a new dependency needs a reason the stdlib can't cover.
+
+## Testing
+
+- Every except/validation branch gets a test asserting type and message.
+- Keep unit tests offline and sub-second; mark anything slower as integration.

templates/python/scaffold/docs/playbooks/python-library.md

@@ -0,0 +1,35 @@
+# Python Library / CLI Playbook
+
+Project: {{PROJECT_NAME}} · Stack: {{STACK}} · Updated: {{DATE}}
+
+## When to use
+
+Use this playbook for any task that creates or modifies Python modules,
+CLI commands, or MCP tools in this project — packaging, public API shape,
+and test layout decisions all route here.
+
+## Always read
+
+1. `docs/engineering/python-rules.md` — canonical Python policy for this project
+2. `AGENTS.md` § critical rules — workflow contract
+
+## Recipe — add a module / public function
+
+1. Place code under the package root (`src/<package>/`); never grow a flat
+   `utils.py` — name modules by domain.
+2. Public API is exported explicitly (`__all__` or package `__init__`);
+   everything else is private by underscore convention.
+3. Type-hint every public signature; run the project's type checker if configured.
+4. Write the test FIRST for bug fixes (red → green) and alongside for features:
+   `tests/test_<module>.py`, mirroring the package layout.
+
+## Recipe — add a CLI command
+
+1. One command = one function with explicit params; parse with the project's
+   CLI framework (argparse/click/typer) — never `sys.argv` by hand.
+2. Errors exit non-zero with an actionable one-line message on stderr.
+3. Cover happy path + each error path with CliRunner-style tests.
+
+## Verify
+
+`pytest tests/ -q` for the touched module (targeted file first, then the suite).