@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/typescript/error-handling.md

@@ -0,0 +1,216 @@
+# Error Handling
+
+## Core Rules
+
+- Never swallow errors silently
+- Never hide the original error context
+- Never replace a specific error with a generic one
+- Preserve HTTP status codes and original payloads
+- Validate inputs before state transitions
+
+## DO
+
+```ts
+// Preserve original error context
+try {
+  await db.user.create({ data });
+} catch (error) {
+  throw new DatabaseError("Failed to create user", { cause: error });
+}
+
+// Use custom error classes for categorized errors
+class NotFoundError extends Error {
+  readonly statusCode = 404;
+  constructor(resource: string, id: string) {
+    super(`${resource} with id '${id}' not found`);
+    this.name = "NotFoundError";
+  }
+}
+
+// Log with context, not just a message
+logger.error("Invoice creation failed", {
+  userId,
+  invoiceData,
+  error: err.message,
+});
+```
+
+## DO NOT
+
+```ts
+// BAD — swallows the error
+try {
+  await riskyOperation();
+} catch {
+  // silent
+}
+
+// BAD — loses original context
+try {
+  await riskyOperation();
+} catch {
+  throw new Error("Something went wrong");
+}
+
+// BAD — catches too broadly
+try {
+  const user = await fetchUser(id);
+  const profile = await fetchProfile(user.profileId);
+  const invoices = await fetchInvoices(user.id);
+} catch (error) {
+  // which operation failed? unknown
+  console.error(error);
+}
+```
+
+## Async Rules
+
+### Prefer async/await Over .then() Chains
+
+For sequential async flow, `async/await` is far more readable than chained `.then().catch()`. Reserve `.then()` / `.catch()` for fire-and-forget side effects.
+
+```ts
+// GOOD — linear, easy to follow, errors propagate naturally
+async function loadDashboard(userId: string) {
+  const user = await fetchUser(userId);
+  const profile = await fetchProfile(user.profileId);
+  const invoices = await fetchInvoices(user.id);
+  return { user, profile, invoices };
+}
+
+// BAD — nested .then chains, harder to read and reason about
+function loadDashboard(userId: string) {
+  return fetchUser(userId)
+    .then((user) =>
+      fetchProfile(user.profileId).then((profile) =>
+        fetchInvoices(user.id).then((invoices) => ({ user, profile, invoices })),
+      ),
+    )
+    .catch((error) => {
+      // which step failed? unclear
+    });
+}
+```
+
+### Always Await or Return
+
+```ts
+// GOOD
+async function loadUser(id: string) {
+  const user = await fetchUser(id);
+  return user;
+}
+
+// BAD — floating promise, errors lost
+async function loadUser(id: string) {
+  fetchUser(id); // unawaited
+}
+```
+
+### Fire-and-Forget Operations
+
+`.catch()` is appropriate when you intentionally don't await:
+
+```ts
+sendAnalyticsEvent(payload).catch((error) => {
+  logger.warn("Analytics event failed", { error });
+});
+
+// If you genuinely don't care about errors, mark intent with `void`
+void sendAnalyticsEvent(payload);
+```
+
+### Parallel Operations
+
+Run independent async operations in parallel with `Promise.all`:
+
+```ts
+// GOOD — parallel, faster
+const [user, settings, invoices] = await Promise.all([
+  fetchUser(userId),
+  fetchSettings(userId),
+  fetchInvoices(userId),
+]);
+
+// BAD — sequential when there's no dependency between calls
+const user = await fetchUser(userId);
+const settings = await fetchSettings(userId);
+const invoices = await fetchInvoices(userId);
+```
+
+Use `Promise.allSettled` when some failures are acceptable and you want all results regardless.
+
+## Custom Error Classes
+
+```ts
+class AppError extends Error {
+  constructor(
+    message: string,
+    readonly statusCode: number,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = this.constructor.name;
+  }
+}
+
+class ValidationError extends AppError {
+  constructor(message: string, readonly fields: Record<string, string[]>) {
+    super(message, 422);
+  }
+}
+
+class NotFoundError extends AppError {
+  constructor(resource: string, id: string) {
+    super(`${resource} '${id}' not found`, 404);
+  }
+}
+```
+
+## User-Facing Errors
+
+Every user-facing error must:
+
+1. **Explain the failure** — what went wrong, specifically
+2. **Explain the next step** — what the user should do
+3. **Be actionable** — give the user something they can do
+
+```ts
+// BAD
+"Something went wrong. Please try again."
+
+// GOOD
+"We couldn't save your invoice. Check your internet connection and try again.
+If the problem continues, contact support with reference #INV-1234."
+```
+
+## Result Pattern (Optional)
+
+For operations where errors are expected and part of normal flow:
+
+```ts
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+async function parseUser(raw: unknown): Promise<Result<User>> {
+  const result = userSchema.safeParse(raw);
+  if (!result.success) {
+    return { ok: false, error: new ValidationError(result.error.message) };
+  }
+  return { ok: true, value: result.data };
+}
+```
+
+## PRIORITY
+
+```
+Preserve context > Specific messages > Actionable user guidance
+```
+
+## See Also
+
+- [`../react/error-boundaries.md`](../react/error-boundaries.md) — catching render-time errors
+- [`../tooling/observability.md`](../tooling/observability.md) — structured logging, error monitoring
+- [`../security/api-security.md`](../security/api-security.md) — safe error responses
+- [`validation.md`](validation.md) — preventing errors via input validation

package/templates/standards/typescript/naming.md

@@ -0,0 +1,78 @@
+# Naming Conventions
+
+## Core Rule
+
+Names should express intent clearly without requiring the reader to trace the code.
+
+## General Rules
+
+| Pattern | Convention | Example |
+|---|---|---|
+| Variables | `camelCase` | `userProfile`, `isLoading` |
+| Functions | `camelCase`, verb-first | `fetchUser`, `formatCurrency` |
+| Types / Interfaces | `PascalCase` | `UserProfile`, `InvoiceLineItem` |
+| Components | `PascalCase` | `InvoiceTable`, `UserAvatarGroup` |
+| Hooks | `camelCase`, `use` prefix | `useScrollLock`, `useInvoiceSort` |
+| Constants | `SCREAMING_SNAKE_CASE` for module-level literals | `MAX_RETRIES`, `API_BASE_URL` |
+| Files | `kebab-case` for utilities, `PascalCase` for components | `format-currency.ts`, `InvoiceTable.tsx` |
+| Enum-like objects | `SCREAMING_SNAKE_CASE` keys | `const STATUS = { Active: "ACTIVE" }` |
+
+## DO
+
+- Use full words — no abbreviations unless universally understood (`id`, `url`, `api`)
+- Include the entity in the name: `userId` not `id`, `selectedInvoice` not `selected`
+- Prefix booleans: `isLoading`, `hasError`, `canSubmit`, `shouldFetch`
+- Name async functions clearly: `fetchUser`, `loadDashboard`, not `getData`
+- Name event handlers with `handle` prefix: `handleSubmit`, `handleRowClick`
+
+## DO NOT
+
+- Abbreviate: `usr`, `mgr`, `btn`, `cfg`, `val`, `res`, `req`
+- Use single letters except for loop indices (`i`, `j`) and type parameters (`T`, `K`)
+- Name things by type: `userArray`, `stringValue`, `dataObject`
+- Name things by position: `item1`, `item2`
+- Use generic names: `handleStuff`, `doThing`, `myHelper`, `useData`, `processItem`
+
+## Generics
+
+```ts
+// BAD — single letter gives no context
+function first<T>(arr: T[]): T | undefined
+
+// GOOD — descriptive when it matters
+function mapById<TItem extends { id: string }>(items: TItem[]): Map<string, TItem>
+```
+
+Use single-letter generics (`T`, `K`, `V`) only when the generic is truly unconstrained and the function is simple enough that context is obvious.
+
+## Component Props
+
+Suffix prop type names with `Props`:
+
+```ts
+// components/InvoiceTable.tsx
+interface InvoiceTableProps {
+  invoices: Invoice[];
+  onRowClick: (id: string) => void;
+  isLoading?: boolean;
+}
+```
+
+## Event Handlers
+
+```ts
+// Component props — callback names
+interface ButtonProps {
+  onClick: (event: MouseEvent) => void;   // external API: "on" prefix
+}
+
+// Local handlers — "handle" prefix
+function handleSubmit(event: FormEvent) { ... }
+function handleRowClick(id: string) { ... }
+```
+
+## See Also
+
+- [`../philosophy/readability.md`](../philosophy/readability.md) — names express intent
+- [`rules.md`](rules.md) — explicit, descriptive types
+- [`../react/component-design.md`](../react/component-design.md) — `<ComponentName>Props` interfaces

package/templates/standards/typescript/rules.md

@@ -0,0 +1,159 @@
+# TypeScript Rules
+
+## DO
+
+- Enable `"strict": true` in all projects — no exceptions
+- Prefer union types over enums: `type Status = "active" | "inactive"` not `enum Status`
+- Prefer generated API types (from OpenAPI, tRPC, Prisma) over hand-written DTOs
+- Use schema-driven validation (Zod) for all external data
+- Use explicit, descriptive type names
+- Prefer `interface` over `type` for object shapes. Use `type` only when interfaces cannot express what you need (unions, intersections, mapped/conditional types, primitive aliases)
+- Prefer `unknown` over `any` for untyped external input
+- Prefer `async/await` over `.then().catch()` chains for sequential async flow
+- Use `satisfies` operator to validate against a type without widening
+- Use `const` assertions for literal types where appropriate
+
+## DO NOT
+
+- Use `any` — use `unknown` and narrow
+- Use type assertions (`as SomeType`) unless interfacing with third-party types you cannot change
+- Write duplicate DTOs for the same data shape (frontend + backend)
+- Perform type gymnastics — if a type is hard to write, the underlying design may be wrong
+- Use `// @ts-ignore` or `// @ts-expect-error` without a comment explaining why
+- Use `namespace` or `module` declarations in new code
+
+## Function Declarations Over Arrow Expressions
+
+Use `function` declarations for named, module-level, and exported functions (including React components). Use arrow functions for anonymous callbacks and inline handlers.
+
+```ts
+// GOOD — named functions use declarations
+function formatCurrency(value: number): string {
+  return new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(value);
+}
+
+export function InvoiceTable({ invoices }: InvoiceTableProps) {
+  return <table>...</table>;
+}
+
+// GOOD — anonymous arrows for callbacks and inline handlers
+invoices.map((invoice) => invoice.amount);
+invoices.filter((invoice) => invoice.status === "open");
+<button onClick={() => setOpen(true)}>Open</button>
+
+// BAD — arrow expression assigned to const for a named function
+const formatCurrency = (value: number): string => { ... };
+const InvoiceTable = ({ invoices }: InvoiceTableProps) => { ... };
+```
+
+Reasoning:
+- Function declarations are hoisted — usable before their definition in the file
+- Named functions produce clearer stack traces
+- `export function foo()` is easier to scan than `export const foo = () => ...`
+- `this` binding is irrelevant for module-level functions
+
+## Interfaces Over Type Aliases
+
+Prefer `interface` for object shapes. Use `type` only when `interface` cannot express what you need.
+
+```ts
+// GOOD — interface for object shapes
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+interface InvoiceTableProps {
+  invoices: Invoice[];
+  onRowClick: (id: string) => void;
+}
+
+// GOOD — type for unions, intersections, mapped/conditional types, primitive aliases
+type Status = "active" | "inactive" | "archived";
+type UserId = string;
+type WithTimestamps<T> = T & { createdAt: Date; updatedAt: Date };
+type Nullable<T> = T | null;
+
+// BAD — type for an object shape that interface would handle
+type User = {
+  id: string;
+  name: string;
+};
+```
+
+Reasoning:
+- Interfaces produce clearer error messages
+- Interfaces are open for declaration merging (useful for extending third-party types)
+- `extends` is more readable than intersection types
+- `interface` signals "this is an object shape" — `type` signals "this could be anything"
+
+## Unions Over Enums
+
+```ts
+// BAD
+enum Direction {
+  North = "NORTH",
+  South = "SOUTH",
+}
+
+// GOOD
+type Direction = "NORTH" | "SOUTH";
+
+// GOOD — const object if you need runtime values
+const DIRECTION = {
+  North: "NORTH",
+  South: "SOUTH",
+} as const;
+type Direction = (typeof DIRECTION)[keyof typeof DIRECTION];
+```
+
+## Narrowing Over Assertions
+
+```ts
+// BAD
+const value = data as User;
+
+// GOOD
+if (!isUser(data)) throw new Error("Expected User");
+const value = data; // now narrowed to User
+```
+
+## Avoiding DTO Duplication
+
+Prefer generating types from the API layer:
+
+```ts
+// tRPC — types come from the router
+// Prisma — types come from the schema
+// OpenAPI — types generated from the spec
+// Zod — infer types from schemas
+
+const userSchema = z.object({ id: z.string(), name: z.string() });
+type User = z.infer<typeof userSchema>; // single source of truth
+```
+
+## satisfies
+
+```ts
+const theme = {
+  primary: "#0070f3",
+  secondary: "#1a1a1a",
+} satisfies Record<string, string>;
+
+theme.primary; // string — not widened to Record<string, string>
+```
+
+## PRIORITY
+
+```
+Type safety > Brevity > Cleverness
+```
+
+## See Also
+
+- [anti-patterns.md](anti-patterns.md)
+- [validation.md](validation.md)
+- [naming.md](naming.md)
+- [error-handling.md](error-handling.md)
+- [tsconfig/base.json](tsconfig/base.json)

package/templates/standards/typescript/tsconfig/base.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedIndexedAccess": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noFallthroughCasesInSwitch": true,
+    "allowUnreachableCode": false,
+    "allowUnusedLabels": false,
+    "noUncheckedSideEffectImports": true,
+    "erasableSyntaxOnly": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "moduleDetection": "force",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "exclude": ["node_modules", "dist", "build"]
+}

package/templates/standards/typescript/tsconfig/nextjs.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./react.json",
+  "compilerOptions": {
+    "plugins": [{ "name": "next" }],
+    "moduleResolution": "bundler",
+    "allowJs": true,
+    "incremental": true
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}

package/templates/standards/typescript/tsconfig/react.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "target": "ES2022"
+  }
+}

package/templates/standards/typescript/validation.md

@@ -0,0 +1,104 @@
+# Validation
+
+## Core Rule
+
+Validate all external data at system boundaries. Never trust raw input from users, APIs, or environment variables.
+
+## Preferred Library
+
+**Zod** is the default choice.
+
+**Valibot** is worth evaluating for bundle-size-sensitive contexts (significantly smaller than Zod).
+
+## Schema-First Approach
+
+Define the schema once. Derive types from it. Share the schema across frontend and backend.
+
+```ts
+// shared/schemas/user.schema.ts
+import { z } from "zod";
+
+export const userSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().min(1).max(100),
+  email: z.string().email(),
+  role: z.enum(["admin", "member", "viewer"]),
+  createdAt: z.coerce.date(),
+});
+
+export type User = z.infer<typeof userSchema>;
+```
+
+## Validate at Boundaries
+
+```ts
+// API response — validate before using
+const response = await fetch("/api/users/1");
+const raw = await response.json();
+const user = userSchema.parse(raw); // throws if invalid
+
+// Form submission — validate before submitting
+const formSchema = z.object({
+  name: z.string().min(1, "Name is required"),
+  email: z.string().email("Must be a valid email"),
+});
+
+// Environment variables
+const envSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+});
+
+export const env = envSchema.parse(process.env);
+```
+
+## Safe Parse for Non-Throwing Validation
+
+```ts
+const result = userSchema.safeParse(raw);
+
+if (!result.success) {
+  // result.error.issues contains field-level errors
+  return { error: result.error.flatten() };
+}
+
+const user = result.data;
+```
+
+## Shared FE/BE Schemas
+
+Place shared schemas in a location accessible to both frontend and backend:
+
+```
+shared/
+  schemas/
+    user.schema.ts
+    invoice.schema.ts
+    auth.schema.ts
+```
+
+In a monorepo, export from a shared package:
+
+```ts
+import { userSchema } from "@acme/schemas";
+```
+
+## DO NOT
+
+- Accept `any` from `JSON.parse` without parsing through a schema
+- Duplicate validation logic in both frontend and backend
+- Use manual `if` chains to validate complex shapes — use a schema library
+- Rely on TypeScript types alone for runtime safety — types are erased at runtime
+
+## PRIORITY
+
+```
+Schema-first > Manual validation > No validation
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — general TS rules including no `any`
+- [`../security/validation.md`](../security/validation.md) — validating at API boundaries
+- [`../architecture/api-design.md`](../architecture/api-design.md) — shared schemas across FE/BE
+- [`../react/forms.md`](../react/forms.md) — Zod schemas with TanStack/RHF forms

package/templates/stubs/executors.md

@@ -0,0 +1,49 @@
+# Executors
+
+How this project dispatches a **coder** and a **reviewer**. Hand-written prose, read fresh at dispatch
+time — the exact parallel to [`verify.md`](verify.md), and for the same reason: a skill that hardcodes an
+invocation bakes one machine's setup into a tool that ships everywhere.
+
+Run `/onboard` to fill this in.
+
+## Coder
+
+<!-- Empty means: implement in-host. That is a valid configuration, not a gap.
+
+     If an external coder CLI is configured, write its exact invocation here, including any directory or
+     permission scoping it needs on this machine. The system prompt is context/roles/coder.md.
+
+     Record alongside it whether that executor was actually observed reading this repository unaided, and
+     when. /onboard tests it; the standing rule below says why the answer changes how briefs are written. -->
+
+**Not configured — implement in-host.**
+
+## Reviewer
+
+<!-- Empty means: the host reviews the diff itself against the plan's review checklist. Weaker than an
+     independent reviewer, but still a gate, and it must say which one it ran.
+
+     A host that offers review often offers more than one shape of it — a review subcommand, a review skill
+     it can be asked to run, or both — and they do not review alike. Whichever was chosen, write the exact
+     invocation. Nothing shipped with this tool names one, because the winner differs per host. -->
+
+**Not configured — the host reviews the diff against the plan's review checklist, and says so.**
+
+## The contract, whatever is configured
+
+A review happens, it returns a verdict with a `P0`–`P3` severity on every blocking finding, and a `FAIL`
+writes a finding to [`findings.md`](findings.md) **before** the loopback.
+
+## Standing rules for any external executor
+
+- **Exit code alone proves nothing.** A CLI can exit 0 after hitting a usage limit mid-run, having
+  completed most but not provably all of a brief. Grep the captured output for exhaustion and error
+  markers before trusting a summary, and on a hit check `git status` and each acceptance criterion
+  individually.
+- **Take the model from the CLI's own config**, not from a flag written here. A hardcoded model flag is one
+  more place to update when models turn over, and a rejected model can still exit 0 having written nothing.
+- **No blanket permission-bypass flag.** Scope permissions in the CLI's own config instead. A standing
+  bypass-everything instruction in a committed file is persistent privilege escalation.
+- **Assume the executor can read this repository** unless you have tested otherwise. Briefs cite paths;
+  they do not paste file contents. If an executor genuinely has no filesystem access, say so here — that is
+  the one case where a brief has to carry content inline.