@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/tooling/ci.md

@@ -0,0 +1,128 @@
+# CI and Pull Requests
+
+## Required CI Gates
+
+Every PR must pass these gates before merge:
+
+- **Lint** — `pnpm lint` (Biome or ESLint)
+- **Format** — `pnpm format --check` (Biome or Prettier)
+- **Typecheck** — `pnpm typecheck` (`tsc --noEmit`)
+- **Test** — `pnpm test` (Vitest)
+
+E2E tests (Playwright) are recommended on critical-path branches but may be slower / less frequent.
+
+## Example GitHub Actions Workflow
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm format --check
+      - run: pnpm typecheck
+      - run: pnpm test
+```
+
+For monorepos with Nx, use `nx affected` to skip unchanged projects:
+
+```yaml
+- run: pnpm nx affected --target=lint --base=origin/main
+- run: pnpm nx affected --target=typecheck --base=origin/main
+- run: pnpm nx affected --target=test --base=origin/main
+```
+
+## Pull Request Sizing
+
+### DO
+
+- Keep PRs focused on one concern — easier to review, faster to land
+- Split a refactor and a feature change into separate PRs
+- Open a draft PR early to make work visible
+
+### DO NOT
+
+- Bundle unrelated changes into one PR
+- Mix renames and behavior changes in the same commit
+- Wait until everything is "done" to open a PR
+
+### When Large PRs Are Acceptable
+
+- Mechanical changes (codemod, formatter run) — easy to review despite size
+- Migrations that cannot be split safely
+- Initial scaffolds
+
+## PR Titles and Descriptions
+
+### Title
+
+- Imperative mood: "Add invoice export", not "Added" or "Adds"
+- Under ~70 characters
+- Scoped if the project uses scopes: `invoices: add CSV export`
+
+### Description
+
+Always include:
+- **Summary** — what changed and why, 1–3 bullets
+- **Test plan** — how it was verified
+- **Screenshots** — for UI changes
+
+Use [`templates/pull-request-template.md`](../templates/pull-request-template.md) as a starting point.
+
+## Merge Strategy
+
+**Prefer squash merges.** This keeps `main`'s history linear and readable. Each PR becomes one commit on `main`.
+
+- The PR title becomes the commit message — write it well
+- The PR description becomes the commit body
+- Branch commits are preserved in the PR itself for archeology
+
+Avoid:
+- Merge commits on `main` (history becomes a tangle)
+- Rebase-and-merge without squashing (every WIP commit ends up on `main`)
+
+## Branch Hygiene
+
+- Branch from `main` (or `develop` if your project uses it)
+- Use descriptive branch names: `feature/invoice-csv-export`, `fix/login-redirect-loop`
+- Delete branches after merge
+- Avoid long-lived feature branches — merge early behind a flag if needed
+
+## Worktree-Based Workflows
+
+For AI-assisted PR workflows, use [`@burglekitt/worktree`](https://github.com/burglekitt/worktree) — a CLI utility for managing git worktree branches. Multiple agents (or a human plus an agent) can work on parallel branches in isolated worktrees without stomping on each other.
+
+## CI for Dependency Changes
+
+When dependencies change, CI should:
+- Run a full install (no partial cache)
+- Run security audit (`pnpm audit --audit-level=high`)
+- Re-run all gates
+
+## PRIORITY
+
+```
+Reviewability > Speed > Volume
+Small PRs > Large PRs (unless mechanical)
+```
+
+## See Also
+
+- [`templates/pull-request-template.md`](../templates/pull-request-template.md)
+- [`architecture/refactoring.md`](../architecture/refactoring.md) — incremental refactor strategies
+- [`tooling/biome.md`](biome.md) — lint and format gate

package/templates/standards/tooling/dates.md

@@ -0,0 +1,194 @@
+# Dates, Times, and Timezones
+
+## Core Rules
+
+- Use `Temporal` types for all date/time work — never the legacy `Date` object
+- Store timestamps as UTC (`Temporal.Instant` serialized to ISO 8601)
+- Convert to the user's timezone only at display time (`Temporal.ZonedDateTime`)
+- Use `Temporal.PlainDate` for calendar dates (birthdays, holidays) — not timestamps
+- Never assume the server and client share a timezone
+
+## Preferred Library
+
+Use [`@burglekitt/gmt`](https://github.com/burglekitt/gmt) — a thin layer over the modern [Temporal API](https://tc39.es/proposal-temporal/docs/) for handling date/time, timezones, and arithmetic. Includes a polyfill for environments without native Temporal yet.
+
+Temporal replaces the legacy `Date` object and provides:
+- Immutable types with explicit timezone handling
+- Calendar-aware arithmetic that doesn't break on DST or leap seconds
+- Clear separation between instants, zoned datetimes, plain dates, and durations
+
+## Choosing the Right Temporal Type
+
+| Concept | Type | Use for |
+|---|---|---|
+| A specific moment globally | `Temporal.Instant` | Server timestamps, event times, audit logs |
+| A moment in a specific timezone | `Temporal.ZonedDateTime` | Scheduled local meetings, recurring events |
+| A calendar date with no time | `Temporal.PlainDate` | Birthdays, holidays, due dates |
+| Wall-clock time with no date | `Temporal.PlainTime` | Daily schedules, opening hours |
+| Date + time without timezone | `Temporal.PlainDateTime` | Floating events ("3pm on the 19th, wherever") |
+| A time span | `Temporal.Duration` | TTLs, intervals, elapsed time |
+
+Choosing the right type prevents whole categories of bugs:
+
+```ts
+import { Temporal } from "@burglekitt/gmt";
+
+// Birthday — calendar date, no timezone (avoids "birthday shows wrong day in Pacific time")
+const birthday = Temporal.PlainDate.from("1990-04-12");
+
+// Event — specific instant in time
+const eventAt = Temporal.Instant.from("2026-05-19T15:00:00Z");
+
+// Recurring meeting — wall-clock time bound to a zone
+const meeting = Temporal.ZonedDateTime.from("2026-05-19T10:00-04:00[America/New_York]");
+
+// Duration — for arithmetic
+const ttl = Temporal.Duration.from({ hours: 24 });
+```
+
+## Storage
+
+Store in UTC. The database column should be:
+- PostgreSQL: `TIMESTAMP WITH TIME ZONE` (`timestamptz`)
+- MySQL: `DATETIME` stored in UTC by convention
+- Prisma: `DateTime` (maps to `timestamptz` on Postgres)
+
+Convert between Prisma's `Date` and `Temporal.Instant` at the ORM boundary. Treat Temporal types as canonical inside your application.
+
+```ts
+// Reading from Prisma
+const invoice = await db.invoice.findUnique({ where: { id } });
+const dueAt = Temporal.Instant.fromEpochMilliseconds(invoice.dueDate.getTime());
+
+// Writing to Prisma
+await db.invoice.update({
+  where: { id },
+  data: { dueDate: new Date(dueAt.epochMilliseconds) },
+});
+```
+
+For calendar dates with no time component, use a `DATE` column and `Temporal.PlainDate`:
+
+```prisma
+model User {
+  birthday DateTime @db.Date  // stored as a date, not a timestamp
+}
+```
+
+## API Contracts
+
+Serialize as ISO 8601 strings. Parse and validate with Zod, then convert to Temporal types:
+
+```ts
+import { Temporal } from "@burglekitt/gmt";
+import { z } from "zod";
+
+const invoiceSchema = z.object({
+  id: z.string(),
+  dueDate: z.string().transform((s) => Temporal.Instant.from(s)),
+  createdAt: z.string().transform((s) => Temporal.Instant.from(s)),
+});
+
+type Invoice = z.infer<typeof invoiceSchema>;
+// Invoice["dueDate"] is now Temporal.Instant
+```
+
+For calendar dates, use `PlainDate`:
+
+```ts
+const userSchema = z.object({
+  birthday: z.string().transform((s) => Temporal.PlainDate.from(s)),
+});
+```
+
+## Detecting User Timezone
+
+```ts
+const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+// "America/New_York", "Europe/London", etc.
+```
+
+Store the user's preferred timezone on their profile if they may travel; fall back to browser-detected timezone otherwise.
+
+## Display
+
+Convert to the user's timezone at the edge — in the component, not in storage or transport:
+
+```tsx
+import { Temporal } from "@burglekitt/gmt";
+
+interface InvoiceDateProps {
+  instant: Temporal.Instant;
+  timezone: string;
+}
+
+export function InvoiceDate({ instant, timezone }: InvoiceDateProps) {
+  const zoned = instant.toZonedDateTimeISO(timezone);
+  const formatted = zoned.toLocaleString("en-US", {
+    dateStyle: "medium",
+    timeStyle: "short",
+  });
+  return (
+    <time dateTime={instant.toString()}>
+      {formatted}
+    </time>
+  );
+}
+```
+
+## Arithmetic
+
+Temporal types are immutable — every operation returns a new value:
+
+```ts
+import { Temporal } from "@burglekitt/gmt";
+
+const created = Temporal.Instant.from("2026-05-19T15:00:00Z");
+const dueIn30 = created.add({ days: 30 });
+
+const today = Temporal.Now.plainDateISO();
+const due = Temporal.PlainDate.from("2026-06-18");
+const daysUntilDue = today.until(due, { largestUnit: "days" }).days;
+const isOverdue = Temporal.PlainDate.compare(today, due) > 0;
+```
+
+DST and timezone offsets are handled correctly because Temporal knows about calendars and timezones — manual millisecond math does not.
+
+## Relative Time
+
+For "2 hours ago" style display:
+
+```ts
+import { Temporal } from "@burglekitt/gmt";
+
+const elapsed = Temporal.Now.instant().since(invoice.createdAt);
+// elapsed is a Temporal.Duration — format with Intl.RelativeTimeFormat
+const rtf = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+rtf.format(-elapsed.total({ unit: "hour" }), "hour");
+// "2 hours ago"
+```
+
+## DO NOT
+
+- Use the legacy `Date` object for new code — Temporal is strictly better
+- Use `Date.parse` or `new Date("string")` — parse with `Temporal.Instant.from` etc.
+- Compare dates with `<` / `>` operators — use `Temporal.Instant.compare` / `Temporal.PlainDate.compare`
+- Do millisecond arithmetic — use `.add()` / `.subtract()` / `.until()` / `.since()`
+- Mix `Date` and `Temporal` types — convert at the boundary, stay Temporal internally
+- Use a timestamp where a calendar date belongs (causes timezone display bugs)
+- Trust client-supplied timestamps for security-critical logic — derive on the server
+
+## PRIORITY
+
+```
+Temporal types > Date object
+UTC storage > Local storage
+Display at the edge > Display everywhere
+Right type for the concept > Generic timestamp
+```
+
+## See Also
+
+- [`../typescript/validation.md`](../typescript/validation.md) — Zod schemas with Temporal parsing
+- [`prisma.md`](prisma.md) — Prisma date columns
+- [`dependencies.md`](dependencies.md) — when to prefer native APIs

package/templates/standards/tooling/dependencies.md

@@ -0,0 +1,90 @@
+# Dependencies
+
+## Core Rule
+
+Every dependency is a long-term liability. Add one only when the value clearly exceeds the cost.
+
+## DO
+
+- Prefer browser-native or runtime-native APIs when they exist
+- Prefer mature, well-maintained libraries with active commits and a healthy issue tracker
+- Check bundle impact before adding any client-side dependency (`bundlephobia.com`)
+- Commit a lockfile (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`)
+- Pin exact versions for tooling that breaks easily across minor updates (linters, formatters, build tools)
+- Audit dependencies periodically (`pnpm audit`, Dependabot, Renovate)
+
+## DO NOT
+
+- Add a dependency to avoid writing 5–20 lines of straightforward code (`left-pad`, `is-array`, `is-odd`)
+- Add a dependency for a feature already provided by the platform (`lodash.clone` → `structuredClone`, `axios` → `fetch`)
+- Add unmaintained packages (no commits in 2+ years, open issues piling up, last release stale)
+- Add packages with license incompatibilities (GPL into proprietary code, etc.)
+- Add packages that pull in massive transitive dependency trees for trivial features
+
+## Native Over Library
+
+Prefer the platform when it does the job:
+
+| Instead of… | Use… |
+|---|---|
+| `lodash.clone`, `lodash.cloneDeep` | `structuredClone` |
+| `axios` | `fetch` |
+| `moment`, `date-fns` (for simple cases) | `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat` |
+| `uuid` (for non-cryptographic IDs) | `crypto.randomUUID()` |
+| `query-string` | `URLSearchParams` |
+| `classnames` | `clsx` (smaller) or template strings |
+| `lodash.debounce`, `lodash.throttle` | tiny custom util or `@uidotdev/usehooks` |
+
+## Evaluating a Library
+
+Before adding, check:
+
+1. **Maintenance** — last release date, commit frequency, issue response time
+2. **Adoption** — weekly downloads on npm, GitHub stars relative to age
+3. **Bundle size** — `bundlephobia.com/package/<name>` for minified + gzipped size
+4. **Transitive deps** — what does it pull in?
+5. **Alternatives** — is there a smaller / more focused option?
+6. **License** — compatible with your project
+
+## Bundle Impact Tools
+
+```bash
+# Inspect the size of a published package
+npx bundlephobia <package-name>
+
+# Visualize what's in your bundle
+pnpm dlx source-map-explorer dist/assets/*.js
+
+# Vite plugin for bundle analysis
+pnpm add -D rollup-plugin-visualizer
+```
+
+## When to Vendor or Fork
+
+Vendor (copy into your repo) when:
+- The library is unmaintained but you need a small piece of it
+- You need a small modification the maintainer won't accept
+- The package is so small (< 50 lines) that the dependency overhead exceeds the code
+
+Fork when:
+- You need a sustained, significant modification
+- You can commit to maintaining the fork
+
+## Lockfile Discipline
+
+- Always commit the lockfile
+- Use the same package manager across the team (pnpm preferred — strict, fast, disk-efficient)
+- Use `pnpm install --frozen-lockfile` in CI
+
+## PRIORITY
+
+```
+Native API > Tiny focused library > Mature comprehensive library > Custom code
+```
+
+## See Also
+
+- [`biome.md`](biome.md) — replacing ESLint + Prettier with one tool
+- [`vite.md`](vite.md) — bundle analysis
+- [`ci.md`](ci.md) — security audits in CI
+- [`dates.md`](dates.md) — date library recommendation

package/templates/standards/tooling/nx.md

@@ -0,0 +1,113 @@
+# Nx
+
+## Purpose
+
+Nx is the build system and task orchestrator for monorepos. It provides:
+
+- Affected command computation (only build/test what changed)
+- Local and remote caching
+- Generators for scaffolding
+- Dependency graph visualization
+
+## Key Commands
+
+```bash
+# Run a target for a specific project
+nx build web
+nx test api
+nx lint ui
+
+# Run a target for all projects
+nx run-many --target=build
+nx run-many --target=test --parallel=3
+
+# Only run for affected projects (CI-optimized)
+nx affected --target=build --base=main
+nx affected --target=test --base=main
+
+# Visualize the dependency graph
+nx graph
+
+# Generate code
+nx generate @nx/react:component InvoiceTable --project=web
+nx generate @nx/node:library schemas --directory=packages/schemas
+```
+
+## Project Configuration
+
+Each project has a `project.json`:
+
+```json
+{
+  "name": "web",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "@nx/vite:build",
+      "options": { "outputPath": "dist/apps/web" }
+    },
+    "dev": {
+      "executor": "@nx/vite:dev-server",
+      "options": { "buildTarget": "web:build" }
+    },
+    "test": {
+      "executor": "@nx/vite:test"
+    },
+    "lint": {
+      "executor": "@nx/eslint:lint"
+    },
+    "typecheck": {
+      "executor": "nx:run-commands",
+      "options": { "command": "tsc --noEmit" }
+    }
+  }
+}
+```
+
+## Caching
+
+Nx caches task outputs by default. CI should use Nx Cloud or remote cache:
+
+```bash
+# nx.json
+{
+  "tasksRunnerOptions": {
+    "default": {
+      "runner": "nx-cloud",
+      "options": {
+        "cacheableOperations": ["build", "test", "lint", "typecheck"]
+      }
+    }
+  }
+}
+```
+
+## Enforcing Boundaries
+
+```json
+// nx.json
+{
+  "targetDefaults": {},
+  "namedInputs": {},
+  "generators": {
+    "@nx/react": {
+      "library": { "bundler": "vite" }
+    }
+  }
+}
+```
+
+Use `@nx/eslint-plugin` with `enforce-module-boundaries` to prevent cross-boundary imports.
+
+## DO NOT
+
+- Skip `nx affected` in CI — it is the primary value proposition of Nx
+- Manually run all tests when only one project changed
+- Create circular dependencies between projects
+- Publish packages unless explicitly required for external consumption
+
+## See Also
+
+- [`../architecture/monorepos.md`](../architecture/monorepos.md) — when and how to use a monorepo
+- [`../architecture/dependency-boundaries.md`](../architecture/dependency-boundaries.md) — enforcing imports
+- [`ci.md`](ci.md) — `nx affected` in CI

package/templates/standards/tooling/observability.md

@@ -0,0 +1,183 @@
+# Observability — Logging, Metrics, Errors
+
+## Core Rules
+
+- Log with structured context — never raw strings without metadata
+- Never log PII, secrets, or sensitive payloads
+- Send errors to an error monitoring service (Sentry, Datadog, etc.)
+- Use levels intentionally — `error` is not the same as `warn`
+- Correlate logs with a request / trace ID
+
+## Logging Levels
+
+| Level | Use for |
+|---|---|
+| `error` | An operation failed and the system could not complete the user's intent |
+| `warn` | Something unexpected, but the operation continued (degraded mode, fallback) |
+| `info` | Normal operational events — startup, shutdown, important state changes |
+| `debug` | Detail useful during investigation; off in production |
+
+`error` should page someone. `warn` should not. Use them accordingly.
+
+## Structured Logging
+
+Log objects, not strings. Structured logs are searchable and indexable in any modern log aggregator:
+
+```ts
+// BAD — string concatenation, ungrep-able
+logger.info(`User ${userId} created invoice ${invoiceId} for $${amount}`);
+
+// GOOD — structured fields
+logger.info("invoice.created", {
+  userId,
+  invoiceId,
+  amount,
+  currency: "USD",
+});
+```
+
+Prefer libraries that emit JSON in production:
+
+- **pino** — fast, JSON output, Node.js
+- **winston** — flexible, multi-transport
+- **slog** — built into Go (mentioned for backend parity)
+
+## Context Propagation
+
+Attach request / trace / user context once at the boundary, then log everywhere:
+
+```ts
+// Express / Hono middleware — set request context once
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const logContext = new AsyncLocalStorage<{ requestId: string; userId?: string }>();
+
+app.use((req, res, next) => {
+  const requestId = req.headers["x-request-id"] ?? crypto.randomUUID();
+  logContext.run({ requestId, userId: req.user?.id }, () => next());
+});
+
+// Anywhere in the request — context is automatically included
+function log(message: string, fields: Record<string, unknown> = {}) {
+  const ctx = logContext.getStore();
+  logger.info(message, { ...ctx, ...fields });
+}
+```
+
+## What Not to Log
+
+Never log:
+
+- Passwords (even hashed) — exposure risk if logs leak
+- Tokens, API keys, session IDs
+- Personal data — email, phone, SSN, addresses — unless legally required and access-controlled
+- Full request/response bodies that might contain PII
+- Stripe / payment data — PCI compliance forbids this
+
+Redact at the source:
+
+```ts
+function redactUser(user: User) {
+  return { id: user.id, role: user.role }; // omit email, name, etc.
+}
+
+logger.info("user.action", { user: redactUser(user), action: "login" });
+```
+
+## Error Monitoring
+
+Use a hosted service (Sentry, Datadog, Honeybadger, Bugsnag). Setup once at app entry:
+
+```ts
+// app/providers.tsx (client) or server entry
+import * as Sentry from "@sentry/react";
+
+Sentry.init({
+  dsn: env.SENTRY_DSN,
+  environment: env.NODE_ENV,
+  tracesSampleRate: 0.1,
+  replaysSessionSampleRate: 0.01,
+  beforeSend(event) {
+    // strip PII before sending
+    if (event.user) delete event.user.email;
+    return event;
+  },
+});
+```
+
+Send errors from:
+
+- React error boundaries (`onError` callback) — see [`react/error-boundaries.md`](../react/error-boundaries.md)
+- Server-side error middleware
+- TanStack Query `onError` callbacks
+- Unhandled promise rejections / uncaught exceptions
+
+## Correlating Frontend and Backend
+
+Attach a request ID header on every API call. The backend echoes it in responses and logs it. Sentry / Datadog can then stitch frontend + backend traces:
+
+```ts
+// Frontend
+const requestId = crypto.randomUUID();
+const response = await fetch("/api/invoices", {
+  headers: { "X-Request-ID": requestId },
+});
+
+// On error — include requestId in the error report
+Sentry.captureException(error, { tags: { requestId } });
+```
+
+## Metrics
+
+For latency, throughput, and business metrics, prefer:
+
+- **Vercel Analytics / Cloudflare Analytics** — out-of-the-box for frontend
+- **OpenTelemetry** — vendor-neutral, integrates with most backends
+- **Prometheus / Grafana** — self-hosted
+
+Track:
+- Request latency (p50, p95, p99)
+- Error rate by route
+- Critical business events (signups, conversions, purchases)
+
+## Web Vitals
+
+For frontend perceived performance, monitor Core Web Vitals:
+
+```ts
+import { onCLS, onFID, onLCP, onINP, onTTFB } from "web-vitals";
+
+function send(metric: { name: string; value: number; id: string }) {
+  fetch("/api/metrics", {
+    method: "POST",
+    body: JSON.stringify(metric),
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+onCLS(send);
+onLCP(send);
+onINP(send);
+onTTFB(send);
+```
+
+## DO NOT
+
+- Log to `console.log` in production code — use a logger
+- Catch errors and log without re-throwing (silently swallows failures)
+- Log inside hot loops without rate limiting
+- Send 100% of traffic to a paid APM — sample appropriately
+
+## PRIORITY
+
+```
+Structured logs > String logs
+Errors reported > Errors only logged
+Correlated traces > Isolated logs
+```
+
+## See Also
+
+- [`typescript/error-handling.md`](../typescript/error-handling.md) — error patterns
+- [`react/error-boundaries.md`](../react/error-boundaries.md) — React error reporting
+- [`security/secrets.md`](../security/secrets.md) — what not to log