@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/examples/bad/prop-drilling.tsx

@@ -0,0 +1,70 @@
+/**
+ * BAD: Drilling `user` through layers that never use it
+ *
+ * Problems:
+ * - Layout and Sidebar accept `user` only to forward it — they don't render it
+ * - Every intermediate signature grows when shared values are added
+ * - Refactoring any layer ripples through the whole tree
+ * - TypeScript noise: prop types repeated everywhere
+ */
+
+interface User {
+  id: string;
+  name: string;
+}
+
+interface PageProps {
+  user: User;
+}
+
+export function Page({ user }: PageProps) {
+  // ✗ Layout doesn't use `user` — only forwards it
+  return <Layout user={user} />;
+}
+
+interface LayoutProps {
+  user: User;
+}
+
+function Layout({ user }: LayoutProps) {
+  return (
+    <div>
+      <Header />
+      {/* ✗ Sidebar doesn't use `user` either — just forwards */}
+      <Sidebar user={user} />
+      <Content />
+    </div>
+  );
+}
+
+interface SidebarProps {
+  user: User;
+}
+
+function Sidebar({ user }: SidebarProps) {
+  return (
+    <aside>
+      <Nav />
+      {/* Finally, UserMenu actually uses the prop */}
+      <UserMenu user={user} />
+    </aside>
+  );
+}
+
+interface UserMenuProps {
+  user: User;
+}
+
+function UserMenu({ user }: UserMenuProps) {
+  return <button type="button">{user.name}</button>;
+}
+
+function Header() {
+  return <header />;
+}
+function Content() {
+  return <main />;
+}
+function Nav() {
+  return <nav />;
+}

package/templates/standards/examples/good/data-fetching.tsx

@@ -0,0 +1,53 @@
+/**
+ * GOOD: Data fetching with TanStack Query
+ *
+ * - Caches, deduplicates, and refetches automatically
+ * - Loading and error states are first-class
+ * - No race conditions
+ * - No useEffect / useState for fetch state
+ */
+
+import { useQuery } from "@tanstack/react-query";
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+async function fetchUser(id: string): Promise<User> {
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) throw new Error(`Failed to fetch user: ${response.statusText}`);
+  return response.json();
+}
+
+interface UserProfileProps {
+  userId: string;
+}
+
+export function UserProfile({ userId }: UserProfileProps) {
+  const { data: user, isLoading, error } = useQuery({
+    queryKey: ["user", userId],
+    queryFn: () => fetchUser(userId),
+    staleTime: 60_000,
+  });
+
+  if (error) {
+    return (
+      <div role="alert">
+        We couldn't load this profile. Please refresh and try again.
+      </div>
+    );
+  }
+
+  if (isLoading || !user) {
+    return <div aria-busy="true">Loading…</div>;
+  }
+
+  return (
+    <article>
+      <h1>{user.name}</h1>
+      <p>{user.email}</p>
+    </article>
+  );
+}

package/templates/standards/examples/good/derived-state.tsx

@@ -0,0 +1,52 @@
+/**
+ * GOOD: Derived values computed during render
+ *
+ * - One source of truth (items + search)
+ * - No re-renders triggered by syncing state to state
+ * - Fewer bugs: filtered/total are always in sync with inputs
+ */
+
+import { useState } from "react";
+
+interface Item {
+  id: string;
+  name: string;
+  price: number;
+}
+
+interface ItemListProps {
+  items: Item[];
+}
+
+export function ItemList({ items }: ItemListProps) {
+  const [search, setSearch] = useState("");
+
+  // Computed during render — always in sync, no useEffect needed
+  const filtered = items.filter((item) =>
+    item.name.toLowerCase().includes(search.toLowerCase()),
+  );
+  const total = filtered.reduce((sum, item) => sum + item.price, 0);
+
+  return (
+    <section>
+      <label>
+        Search
+        <input
+          type="search"
+          value={search}
+          onChange={(event) => setSearch(event.target.value)}
+        />
+      </label>
+      <p>
+        {filtered.length} items — total ${total.toFixed(2)}
+      </p>
+      <ul>
+        {filtered.map((item) => (
+          <li key={item.id}>
+            {item.name} — ${item.price.toFixed(2)}
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}

package/templates/standards/examples/good/feature-component.tsx

@@ -0,0 +1,141 @@
+/**
+ * GOOD EXAMPLE: Feature-driven, colocated, accessible invoice table
+ *
+ * Demonstrates:
+ * - Feature-colocated hook and types
+ * - TanStack Query for server state
+ * - URL state for filters
+ * - Accessible table markup
+ * - Explicit props, no spreading unknown props
+ * - No useEffect for data fetching or derived state
+ * - Controlled loading and error states
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import { useSearch } from "@tanstack/react-router";
+import { type Invoice, invoiceSchema } from "./invoice.schema";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+interface InvoiceTableProps {
+  onRowClick: (id: string) => void;
+}
+
+// ─── Data fetching ─────────────────────────────────────────────────────────────
+
+async function fetchInvoices(status: string): Promise<Invoice[]> {
+  const response = await fetch(`/api/invoices?status=${status}`);
+  if (!response.ok) throw new Error(`Failed to fetch invoices: ${response.statusText}`);
+  const data = await response.json();
+  return invoiceSchema.array().parse(data);
+}
+
+// ─── Feature hook ─────────────────────────────────────────────────────────────
+
+function useInvoiceTable() {
+  // URL state — shareable, bookmarkable
+  const { status = "all" } = useSearch({ from: "/invoices" });
+
+  const { data: invoices = [], isLoading, error } = useQuery({
+    queryKey: ["invoices", status],
+    queryFn: () => fetchInvoices(status),
+    staleTime: 30_000,
+  });
+
+  // Derived state — computed during render, no useEffect
+  const totalAmount = invoices.reduce((sum, inv) => sum + inv.amount, 0);
+
+  return { invoices, isLoading, error, totalAmount, status };
+}
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+export function InvoiceTable({ onRowClick }: InvoiceTableProps) {
+  const { invoices, isLoading, error, totalAmount } = useInvoiceTable();
+
+  if (error) {
+    return (
+      <div role="alert">
+        <p>We couldn't load your invoices. Please refresh the page or contact support.</p>
+        <p>
+          <small>Error: {error.message}</small>
+        </p>
+      </div>
+    );
+  }
+
+  if (isLoading) {
+    return <div aria-busy="true" aria-label="Loading invoices">Loading…</div>;
+  }
+
+  if (invoices.length === 0) {
+    return <p>No invoices found.</p>;
+  }
+
+  return (
+    <section aria-labelledby="invoice-table-heading">
+      <h2 id="invoice-table-heading">Invoices</h2>
+      <table>
+        <caption>
+          {invoices.length} invoices — total:{" "}
+          {new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(
+            totalAmount,
+          )}
+        </caption>
+        <thead>
+          <tr>
+            <th scope="col">Title</th>
+            <th scope="col">Status</th>
+            <th scope="col">Amount</th>
+            <th scope="col">Due Date</th>
+            <th scope="col"><span className="sr-only">Actions</span></th>
+          </tr>
+        </thead>
+        <tbody>
+          {invoices.map((invoice) => (
+            <InvoiceRow
+              key={invoice.id}
+              invoice={invoice}
+              onRowClick={onRowClick}
+            />
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+// ─── Sub-component ─────────────────────────────────────────────────────────────
+
+interface InvoiceRowProps {
+  invoice: Invoice;
+  onRowClick: (id: string) => void;
+}
+
+function InvoiceRow({ invoice, onRowClick }: InvoiceRowProps) {
+  return (
+    <tr>
+      <td>{invoice.title}</td>
+      <td>{invoice.status}</td>
+      <td>
+        {new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" }).format(
+          invoice.amount,
+        )}
+      </td>
+      <td>
+        <time dateTime={invoice.dueDate.toISOString()}>
+          {invoice.dueDate.toLocaleDateString()}
+        </time>
+      </td>
+      <td>
+        <button
+          type="button"
+          onClick={() => onRowClick(invoice.id)}
+          aria-label={`View invoice: ${invoice.title}`}
+        >
+          View
+        </button>
+      </td>
+    </tr>
+  );
+}

package/templates/standards/examples/good/invoice.schema.ts

@@ -0,0 +1,20 @@
+/**
+ * Schema for the InvoiceTable example.
+ *
+ * Demonstrates the standards-preferred pattern:
+ * - Single Zod schema as source of truth
+ * - Inferred TypeScript type from the schema
+ * - Shared between FE and BE (in a real project this would live in shared/schemas/)
+ */
+
+import { z } from "zod";
+
+export const invoiceSchema = z.object({
+  id: z.string().cuid(),
+  title: z.string().min(1).max(200),
+  status: z.enum(["draft", "open", "paid", "void"]),
+  amount: z.number().nonnegative(),
+  dueDate: z.coerce.date(),
+});
+
+export type Invoice = z.infer<typeof invoiceSchema>;

package/templates/standards/examples/good/prop-drilling.tsx

@@ -0,0 +1,83 @@
+/**
+ * GOOD: Context provides user data where it's actually needed
+ *
+ * - Intermediate components carry no extra props
+ * - Adding new shared data doesn't require updating every layer
+ * - Tree is composed declaratively at the top
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+interface UserContextValue {
+  user: User;
+}
+
+const UserContext = createContext<UserContextValue | null>(null);
+
+interface UserProviderProps {
+  user: User;
+  children: ReactNode;
+}
+
+export function UserProvider({ user, children }: UserProviderProps) {
+  return <UserContext.Provider value={{ user }}>{children}</UserContext.Provider>;
+}
+
+function useCurrentUser(): User {
+  const context = useContext(UserContext);
+  if (!context) throw new Error("useCurrentUser must be used within UserProvider");
+  return context.user;
+}
+
+// ─── Components — no `user` prop forwarded through the tree ───────────────────
+
+interface PageProps {
+  user: User;
+}
+
+export function Page({ user }: PageProps) {
+  return (
+    <UserProvider user={user}>
+      <Layout />
+    </UserProvider>
+  );
+}
+
+function Layout() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+      <Content />
+    </div>
+  );
+}
+
+function Sidebar() {
+  return (
+    <aside>
+      <Nav />
+      <UserMenu />
+    </aside>
+  );
+}
+
+function UserMenu() {
+  const user = useCurrentUser();
+  return <button type="button">{user.name}</button>;
+}
+
+function Header() {
+  return <header />;
+}
+function Content() {
+  return <main />;
+}
+function Nav() {
+  return <nav />;
+}

package/templates/standards/philosophy/ai-agent-behavior.md

@@ -0,0 +1,93 @@
+# AI Agent Behavior
+
+Rules for AI agents (Claude Code, Cursor, Continue, Copilot, etc.) working within a codebase governed by these standards.
+
+## Stack Selection
+
+The primary stack is **TypeScript on Node.js with React on the frontend**. Default to this stack for:
+
+- New projects
+- New services or modules
+- Greenfield features
+- Any task where the language is not already chosen
+
+**PHP standards exist in [`../php/`](../php/) but are secondary.** Load and apply them only when:
+
+- The user explicitly asks for PHP
+- You are working inside an existing PHP codebase
+- The task involves modifying a PHP file
+
+Do not propose rewriting a Node/TypeScript codebase in PHP. Do not suggest PHP as an alternative to JavaScript/TypeScript "for performance" or "for simplicity." If the user has not specified PHP, they want TypeScript.
+
+## PRIORITIZE
+
+- Readability
+- Accessibility
+- Composability
+- Maintainability
+- Type safety
+- Feature isolation
+- Incremental refactoring
+- Explicit APIs
+- Predictable architecture
+
+## AVOID
+
+- Giant files (trigger decomposition review)
+- `useEffect` abuse (derived state, state sync, data orchestration)
+- Premature abstractions
+- Hook mini-frameworks
+- Defensive memoization
+- Over-generalized utilities
+- Excessive inheritance
+- Redux
+- Hidden side effects
+- Implementation testing (test behavior, not internals)
+- State synchronization effects
+- Aggressive rewrites without explicit approval
+
+## REFACTORING RULES
+
+### DO
+
+- Preserve behavior when refactoring
+- Prefer additive refactors (add new, migrate, delete old)
+- Write tests before refactoring untested code where possible
+- Preserve architecture boundaries
+- Migrate legacy systems gently and incrementally
+
+### DO NOT
+
+- Perform massive rewrites unless explicitly requested
+- Introduce major architectural divergence without asking first
+- Break existing behavior in the name of improvement
+- Rename aggressively across unrelated files in a single PR
+
+## ASKING VS. PROCEEDING
+
+Ask before:
+- Changing state management strategy
+- Reorganizing folder structure significantly
+- Replacing a library or major dependency
+- Changing the testing approach for a module
+- Any action that affects more than the immediate task
+
+Proceed without asking for:
+- Small, contained refactors within a single file
+- Fixing obvious bugs that are clearly unintentional
+- Adding types to untyped code
+- Improving accessibility of existing components
+
+## OUTPUT QUALITY EXPECTATIONS
+
+- Every change must leave the codebase at least as readable as it was found
+- Every change must leave the codebase at least as accessible as it was found
+- No regressions in type coverage
+- No new `any` types without explicit justification
+- No new `useEffect` without a clear external synchronization reason
+
+## See Also
+
+- [`core-principles.md`](core-principles.md) — the architectural values these rules implement
+- [`../architecture/refactoring.md`](../architecture/refactoring.md) — incremental refactoring rules
+- [`../react/anti-patterns.md`](../react/anti-patterns.md) — patterns to avoid in React code

package/templates/standards/philosophy/core-principles.md

@@ -0,0 +1,49 @@
+# Core Engineering Principles
+
+## Core Principle
+
+Prefer explicit, composable, feature-oriented architecture over generalized abstractions and centralized complexity.
+
+## Architectural Values
+
+### DO
+
+- Composition over inheritance
+- Readability over cleverness
+- Explicitness over magic
+- Feature ownership over centralized organization
+- Incremental abstraction over premature DRY
+- Maintainability over premature optimization
+- Colocation over fragmentation
+- Accessibility-first development
+- Strong type safety
+- Predictable data flow
+
+### PRIORITY
+
+```
+Readability > Maintainability > Performance > Cleverness
+```
+
+## Applying These Values
+
+**Colocation** — Keep feature-specific code inside the feature. Move to shared only when genuinely reused by 3+ features.
+
+**Incrementalism** — Start simple. Add abstraction when the need is proven, not anticipated.
+
+**Explicitness** — Prefer code that is obvious over code that is elegant. A future reader should not need to trace magic to understand behavior.
+
+**Feature ownership** — A feature folder owns its components, hooks, types, and tests. It does not scatter logic across the codebase by type.
+
+**Accessibility first** — Semantic HTML and keyboard support are not optional. They are part of the definition of done.
+
+**Type safety** — Types are documentation and safety nets. Avoid `any`, type assertions, and type gymnastics.
+
+**Predictable data flow** — Data flows downward. Side effects are explicit and isolated. State changes are traceable.
+
+## See Also
+
+- [`ai-agent-behavior.md`](ai-agent-behavior.md) — concrete rules derived from these principles
+- [`maintainability.md`](maintainability.md) — colocation, deletability, naming
+- [`readability.md`](readability.md) — obvious over clever
+- [`incremental-abstraction.md`](incremental-abstraction.md) — when to abstract vs. inline

package/templates/standards/philosophy/incremental-abstraction.md

@@ -0,0 +1,56 @@
+# Incremental Abstraction
+
+## Core Rule
+
+Abstract when the need is proven. Inline when the need is uncertain.
+
+## The Three-Instance Rule
+
+Do not extract a shared abstraction until you have at least three real, distinct use cases. Two similar things may be coincidence. Three is a pattern.
+
+## Progression
+
+```
+Inline → Local function → Shared utility → Published package
+```
+
+Move right only when left is insufficient. Do not start at the right.
+
+## DO
+
+- Duplicate small pieces of logic until the pattern is clear
+- Extract to a local function first, before considering a shared module
+- Name extracted abstractions after what they do, not what they contain
+- Keep abstractions small and single-purpose
+
+## DO NOT
+
+- Create a utility file on the first use
+- Extract "just in case" it is needed elsewhere
+- Build generic frameworks from a single use case
+- Name abstractions by what they wrap (`useUserData` wrapping `useQuery` is not an abstraction — it is indirection)
+
+## Signs You Are Abstracting Too Early
+
+- The abstraction has only one caller
+- The abstraction has more configuration options than callers
+- You are passing flags to switch between behaviors (`isEdit`, `mode: 'create' | 'edit'`)
+- The abstraction is harder to understand than the code it replaces
+
+## Signs You Should Abstract Now
+
+- Three or more places duplicate the same logic with minor variations
+- A bug was fixed in one place but exists in two others
+- A feature requirement forced you to update the same logic in multiple files
+
+## PRIORITY
+
+```
+Clarity of local code > DRY
+```
+
+## See Also
+
+- [`maintainability.md`](maintainability.md) — deletability and naming
+- [`../architecture/shared-code.md`](../architecture/shared-code.md) — when to promote to `shared/`
+- [`../architecture/refactoring.md`](../architecture/refactoring.md) — additive refactor strategy

package/templates/standards/philosophy/maintainability.md

@@ -0,0 +1,66 @@
+# Maintainability
+
+## Core Rule
+
+Write code that the next engineer (or AI agent) can understand, change, and delete safely.
+
+## DO
+
+- Colocate feature-specific logic with the feature
+- Delete dead code rather than commenting it out
+- Name things after their intent, not their implementation
+- Keep functions and components focused on a single responsibility
+- Make dependencies explicit (imports, props, parameters)
+- Prefer flat structures over deep nesting
+- Write the simplest thing that works
+
+## DO NOT
+
+- Leave commented-out code without a dated explanation
+- Create files that "might be useful later"
+- Hide behavior inside abstractions named too generically (`utils.ts`, `helpers.ts`, `common.ts`)
+- Use abbreviations that require domain knowledge to decode
+- Rely on implicit global state or module-level side effects
+- Write clever code when obvious code works
+
+## File Size
+
+Large files are a signal, not a rule violation. Review for decomposition when a file:
+- Exceeds ~300 lines
+- Has multiple unrelated responsibilities
+- Is difficult to scan or navigate
+
+Do not split files purely to hit a line count target.
+
+## Naming
+
+- Name functions after what they do: `formatCurrency`, `fetchUserProfile`
+- Name components after what they render: `InvoiceTable`, `UserAvatarGroup`
+- Name hooks after what behavior they encapsulate: `useScrollLock`, `useDebounce`
+- Avoid: `handleStuff`, `doThing`, `myHelper`, `useData`
+
+## Colocation
+
+```
+features/
+  invoices/
+    InvoiceTable.tsx       ← component
+    InvoiceTable.test.tsx  ← test alongside component
+    useInvoiceSort.ts      ← hook used only here
+    invoice.types.ts       ← types scoped to this feature
+    invoice.api.ts         ← data fetching scoped to this feature
+```
+
+Move to `shared/` only when used across 3+ features.
+
+## PRIORITY
+
+```
+Deletability > Reusability > Cleverness
+```
+
+## See Also
+
+- [`readability.md`](readability.md) — short files, clear names, flat structure
+- [`incremental-abstraction.md`](incremental-abstraction.md) — abstract late, not early
+- [`../architecture/feature-driven.md`](../architecture/feature-driven.md) — colocation as a structural pattern