@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/php/testing.md

@@ -0,0 +1,139 @@
+# PHP Testing
+
+## Tooling
+
+- **Pest** — preferred for new projects; expressive syntax, great DX
+- **PHPUnit** — established standard; use for legacy or teams already on it
+
+Both can coexist in the same project. New tests should follow whichever the codebase uses.
+
+## Test Pyramid
+
+Every modern PHP project should have:
+
+- **Unit tests** — pure logic, value objects, domain services
+- **Integration tests** — application handlers with real database, queue, cache (in containers)
+- **End-to-end tests** — critical user flows via HTTP
+
+Avoid excessive mocking. Integration tests with real (containerized) dependencies catch bugs that mock-heavy unit tests miss.
+
+## Test Behavior, Not Implementation
+
+```php
+// BAD — asserts on method calls (couples test to implementation)
+$user->expects()->method('setStatus')->with('active');
+
+// GOOD — asserts on observable behavior
+expect($user->status())->toBe(UserStatus::Active);
+// or PHPUnit:
+$this->assertEquals(UserStatus::Active, $user->status());
+```
+
+When the implementation changes but the behavior doesn't, the test should still pass.
+
+## Pest Example
+
+```php
+<?php declare(strict_types=1);
+
+use App\Domain\Order;
+use App\Domain\Money;
+
+it('calculates the total with tax', function () {
+    $order = new Order(amount: new Money(100, 'USD'));
+
+    $total = $order->totalWithTax(taxRate: 0.20);
+
+    expect($total)->toEqual(new Money(120, 'USD'));
+});
+
+it('rejects negative amounts', function () {
+    expect(fn () => new Money(-1, 'USD'))
+        ->toThrow(InvalidArgumentException::class);
+});
+```
+
+## PHPUnit Example
+
+```php
+<?php declare(strict_types=1);
+
+namespace Tests\Domain;
+
+use App\Domain\Order;
+use App\Domain\Money;
+use PHPUnit\Framework\TestCase;
+
+final class OrderTest extends TestCase
+{
+    public function test_calculates_total_with_tax(): void
+    {
+        $order = new Order(amount: new Money(100, 'USD'));
+
+        $total = $order->totalWithTax(taxRate: 0.20);
+
+        $this->assertEquals(new Money(120, 'USD'), $total);
+    }
+}
+```
+
+## Integration Tests
+
+For integration tests, use real (containerized) dependencies — not mocks:
+
+```php
+it('creates an invoice and emits an event', function () {
+    $handler = $this->app->make(CreateInvoiceHandler::class);
+
+    $invoice = $handler->handle(new CreateInvoiceCommand(
+        customerId: $this->testCustomer->id,
+        amount: new Money(500, 'USD'),
+    ));
+
+    // Asserts against the real database
+    expect(Invoice::find($invoice->id))->not->toBeNull();
+
+    // Asserts the event was dispatched
+    Event::assertDispatched(InvoiceCreated::class);
+});
+```
+
+## Test Factories
+
+Use factories (Laravel) or fixtures (Symfony) for test data — never hand-construct entities row by row:
+
+```php
+$user = User::factory()->create(['status' => UserStatus::Active]);
+$invoices = Invoice::factory()->count(5)->for($user)->create();
+```
+
+## Coverage Expectations
+
+- Domain layer: aim for high coverage (it's pure logic)
+- Application handlers: integration tests covering happy and error paths
+- Infrastructure adapters: minimal — test the adapter contract, not the third-party library
+- Presentation: tested via HTTP-level integration tests, not controller unit tests
+
+Coverage percentage is a weak proxy. Prefer "every critical flow has at least one integration test" over "85% coverage."
+
+## DO NOT
+
+- Mock things you own — refactor the design instead
+- Use `partialMock`, `Mockery::spy`, or method-call assertions for normal logic
+- Write tests that depend on order
+- Share mutable state between tests
+- Skip writing tests because "it's just a small change"
+
+## PRIORITY
+
+```
+Integration tests with real dependencies > Mock-heavy unit tests
+Behavior assertions > Method-call assertions
+Critical-flow coverage > Coverage percentage
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — typed, testable code by construction
+- [`tooling.md`](tooling.md) — Pest, PHPUnit, CI integration
+- [`../react/testing.md`](../react/testing.md) — same philosophy for the frontend

package/templates/standards/php/tooling.md

@@ -0,0 +1,245 @@
+# PHP Tooling
+
+## Core Stack
+
+| Tool | Purpose | Required? |
+|---|---|---|
+| **Composer** | Dependency management, PSR-4 autoloading | Yes |
+| **PHPStan** | Static analysis | Yes — level max |
+| **Pint** or **PHP-CS-Fixer** | Formatting | Yes |
+| **Pest** or **PHPUnit** | Testing | Yes |
+| **Rector** | Automated refactors, PHP/framework upgrades | Strongly recommended |
+| **Docker** | Containerized dev environment | Strongly recommended |
+| **Xdebug** | Step debugging | Optional but valuable |
+
+## Composer
+
+Never manually `include` files. Use Composer for all autoloading and dependencies.
+
+```bash
+composer install         # install from composer.lock
+composer require <pkg>   # add a runtime dependency
+composer require --dev <pkg>  # dev-only
+composer update          # update within composer.json constraints
+```
+
+PSR-4 autoload mapping:
+
+```json
+{
+  "autoload": {
+    "psr-4": {
+      "App\\": "src/"
+    }
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "Tests\\": "tests/"
+    }
+  }
+}
+```
+
+After changing autoload config, regenerate:
+
+```bash
+composer dump-autoload --optimize
+```
+
+Always commit `composer.lock`.
+
+## PHPStan
+
+Static analysis is **mandatory**. Modern PHP without it is incomplete.
+
+```bash
+composer require --dev phpstan/phpstan
+
+# Run
+vendor/bin/phpstan analyse
+```
+
+`phpstan.neon` baseline:
+
+```yaml
+parameters:
+  level: max
+  paths:
+    - src
+    - tests
+  excludePaths:
+    - vendor
+```
+
+Target **level max** (level 10 as of PHPStan 2). If you're adopting PHPStan into an existing codebase, generate a baseline to suppress existing errors and improve from there:
+
+```bash
+vendor/bin/phpstan analyse --generate-baseline
+```
+
+Then fix baseline entries over time.
+
+### Useful PHPStan Extensions
+
+- `phpstan/phpstan-strict-rules` — additional strictness
+- `phpstan/phpstan-deprecation-rules` — flag deprecated API use
+- Framework extensions: `nunomaduro/larastan` (Laravel), `phpstan/phpstan-symfony`
+- `phpstan/phpstan-phpunit` or `pestphp/pest-plugin-phpstan` for test files
+
+### Psalm Alternative
+
+Psalm is an excellent alternative to PHPStan. Pick one; don't run both.
+
+## Pint / PHP-CS-Fixer
+
+Pick one formatter and let it own style entirely. Never argue about formatting in PRs.
+
+**Pint** (Laravel-flavored, simpler config):
+
+```bash
+composer require --dev laravel/pint
+
+vendor/bin/pint           # format
+vendor/bin/pint --test    # check without writing (CI)
+```
+
+**PHP-CS-Fixer** (more configurable):
+
+```bash
+composer require --dev friendsofphp/php-cs-fixer
+
+vendor/bin/php-cs-fixer fix
+vendor/bin/php-cs-fixer fix --dry-run --diff  # CI
+```
+
+Both default to PSR-12.
+
+## Testing — Pest or PHPUnit
+
+See [`testing.md`](testing.md) for the testing philosophy. Setup:
+
+**Pest:**
+
+```bash
+composer require --dev pestphp/pest pestphp/pest-plugin-laravel  # if Laravel
+vendor/bin/pest --init
+
+vendor/bin/pest
+vendor/bin/pest --coverage
+```
+
+**PHPUnit:**
+
+```bash
+composer require --dev phpunit/phpunit
+
+vendor/bin/phpunit
+```
+
+## Rector
+
+Rector automates refactors — PHP version upgrades, framework upgrades, code modernization. Extremely valuable.
+
+```bash
+composer require --dev rector/rector
+
+# Config in rector.php (sets paths, rules, php version target)
+vendor/bin/rector process
+vendor/bin/rector process --dry-run  # preview without writing
+```
+
+Common rule sets:
+- `LevelSetList::UP_TO_PHP_83`
+- `SetList::CODE_QUALITY`
+- `SetList::DEAD_CODE`
+- `SetList::TYPE_DECLARATION`
+
+## Docker
+
+Dockerize local dev. Avoid "works on my machine" setups.
+
+Typical `docker-compose.yml` services:
+
+```yaml
+services:
+  app:
+    build: .
+    volumes: ['.:/app']
+  nginx:
+    image: nginx:alpine
+    ports: ['8080:80']
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: dev
+    ports: ['5432:5432']
+  redis:
+    image: redis:7-alpine
+    ports: ['6379:6379']
+```
+
+For Laravel: **Sail** wraps this; **Herd** (macOS) gives a local PHP-FPM + DB stack without containers.
+
+## CI Pipeline (Required Gates)
+
+Every PHP repo should run on PR:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [pull_request, push]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: none
+          tools: composer:v2
+      - run: composer install --prefer-dist --no-progress
+      - run: vendor/bin/pint --test
+      - run: vendor/bin/phpstan analyse --no-progress
+      - run: vendor/bin/pest --parallel
+```
+
+CI must fail on:
+- Format violations
+- PHPStan errors
+- Test failures
+- Security audit findings (`composer audit`)
+
+See [`../tooling/ci.md`](../tooling/ci.md) for cross-language CI principles.
+
+## Optional but Useful
+
+- **Telescope** (Laravel) — local request/query/job inspector
+- **Horizon** (Laravel) — queue dashboard
+- **Symfony Profiler** — request profiling
+- **Xdebug** — step debugging
+- **PHP Insights** — code quality metrics
+- **Deptrac** — enforce architectural boundaries
+
+## DO NOT
+
+- Skip PHPStan to "save time" — bugs cost more than analysis
+- Run both Pint and PHP-CS-Fixer in the same project
+- Edit `vendor/` files
+- Commit `vendor/` to git
+- Use globally-installed PHP/Composer in production — pin versions in Docker or Dockerfile
+
+## PRIORITY
+
+```
+PHPStan level max > "It runs" as quality bar
+Automated formatting > Manual style debates
+Rector for upgrades > Manual sed across the codebase
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — the rules that PHPStan helps enforce
+- [`testing.md`](testing.md) — Pest / PHPUnit setup
+- [`frameworks.md`](frameworks.md) — framework-specific tooling additions
+- [`../tooling/ci.md`](../tooling/ci.md) — cross-language CI principles

package/templates/standards/react/accessibility.md

@@ -0,0 +1,130 @@
+# Accessibility
+
+## Core Rule
+
+Accessibility is not optional. It is part of the definition of done.
+
+## Requirements
+
+- Semantic HTML first — use the right element for the job
+- All interactive elements must be keyboard accessible
+- All interactive elements must be usable by screen readers
+- All form inputs must have associated labels
+- Color is never the only means of conveying information
+- Minimum contrast ratio: 4.5:1 for normal text, 3:1 for large text (WCAG AA)
+
+## Semantic HTML
+
+```tsx
+// BAD — no semantics
+<div onClick={handleSubmit}>Submit</div>
+<div className="heading">Invoice Details</div>
+
+// GOOD — correct semantics
+<button type="submit" onClick={handleSubmit}>Submit</button>
+<h2>Invoice Details</h2>
+```
+
+Use the correct element:
+- `<button>` for actions
+- `<a>` for navigation
+- `<h1>`–`<h6>` for headings (in order, no skipping)
+- `<ul>` / `<ol>` / `<li>` for lists
+- `<table>` for tabular data (with `<caption>`, `<th scope>`)
+- `<nav>` for navigation regions
+- `<main>`, `<aside>`, `<header>`, `<footer>` for landmarks
+
+## Form Labeling
+
+```tsx
+// BAD — no label association
+<div>
+  <span>Email</span>
+  <input type="email" />
+</div>
+
+// GOOD — explicit label
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// GOOD — wrapped label
+<label>
+  Email
+  <input type="email" />
+</label>
+```
+
+Never use `placeholder` as a substitute for a label.
+
+## Keyboard Navigation
+
+- All interactive elements must be reachable with Tab
+- All interactive elements must be activatable with Enter or Space
+- Dialogs must trap focus while open and restore focus on close
+- Menus must support Arrow key navigation
+- Escape must close dialogs, dropdowns, and menus
+
+## ARIA — Use Only When Necessary
+
+Prefer semantic HTML. Use ARIA only when a native element cannot express the required semantics.
+
+```tsx
+// BAD — redundant ARIA
+<button role="button" aria-label="Submit">Submit</button>
+
+// GOOD — ARIA only when HTML cannot express it
+<div role="status" aria-live="polite">{statusMessage}</div>
+```
+
+Common correct ARIA uses:
+- `aria-label` / `aria-labelledby` — when visible label is absent
+- `aria-describedby` — for additional descriptions (error messages, help text)
+- `aria-expanded` — for toggleable regions
+- `aria-live` — for dynamic content announcements
+- `aria-invalid` — for form validation errors
+
+## Images
+
+```tsx
+// Decorative — hide from assistive technology
+<img src="decoration.svg" alt="" />
+
+// Informative — describe the content
+<img src="invoice-preview.png" alt="Preview of invoice #1234 for $500" />
+
+// Icon buttons — label the action, not the icon
+<button aria-label="Download invoice">
+  <DownloadIcon aria-hidden="true" />
+</button>
+```
+
+## Focus Visibility
+
+Never remove focus outlines without providing an equivalent visible replacement:
+
+```css
+/* BAD */
+:focus { outline: none; }
+
+/* GOOD */
+:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+```
+
+## shadcn/ui and Radix
+
+Prefer shadcn/ui components built on Radix UI primitives — they handle keyboard navigation and ARIA patterns correctly out of the box. Do not replace them with custom implementations unless there is a specific, documented reason.
+
+## PRIORITY
+
+```
+Semantic HTML > ARIA > Custom implementation
+```
+
+## See Also
+
+- [`component-design.md`](component-design.md) — composable, accessible components
+- [`forms.md`](forms.md) — label, error, and keyboard patterns
+- [`../tooling/shadcn.md`](../tooling/shadcn.md) — Radix-based primitives with a11y built in

package/templates/standards/react/anti-patterns.md

@@ -0,0 +1,187 @@
+# React Anti-Patterns
+
+## Giant Components
+
+```tsx
+// BAD — one component doing everything
+function InvoicePage() {
+  const [invoices, setInvoices] = useState([]);
+  const [filters, setFilters] = useState({});
+  const [sortKey, setSortKey] = useState("date");
+  const [page, setPage] = useState(1);
+  const [selectedIds, setSelectedIds] = useState([]);
+  // ... 200 more lines of JSX, logic, and effects
+}
+
+// GOOD — decomposed, composed
+function InvoicePage() {
+  return (
+    <InvoiceLayout>
+      <InvoiceFilters />
+      <InvoiceTable />
+      <InvoicePagination />
+    </InvoiceLayout>
+  );
+}
+```
+
+## useEffect for Derived State
+
+```tsx
+// BAD
+const [fullName, setFullName] = useState("");
+useEffect(() => {
+  setFullName(`${firstName} ${lastName}`);
+}, [firstName, lastName]);
+
+// GOOD
+const fullName = `${firstName} ${lastName}`;
+```
+
+## useEffect for Data Fetching
+
+```tsx
+// BAD
+const [user, setUser] = useState(null);
+useEffect(() => {
+  fetchUser(id).then(setUser);
+}, [id]);
+
+// GOOD
+const { data: user } = useQuery({
+  queryKey: ["user", id],
+  queryFn: () => fetchUser(id),
+});
+```
+
+## Prop Drilling
+
+Prop drilling is when intermediate components accept props they don't use, only to forward them to a deeper child. The pain compounds as you add more shared values — every layer's signature grows.
+
+```tsx
+// BAD — Layout and Sidebar don't use `user`, they just forward it
+function Page({ user }: { user: User }) {
+  return <Layout user={user} />;
+}
+
+function Layout({ user }: { user: User }) {
+  return (
+    <div>
+      <Header />
+      <Sidebar user={user} />
+      <Content />
+    </div>
+  );
+}
+
+function Sidebar({ user }: { user: User }) {
+  return (
+    <aside>
+      <Nav />
+      <UserMenu user={user} />
+    </aside>
+  );
+}
+
+function UserMenu({ user }: { user: User }) {
+  return <button>{user.name}</button>;
+}
+
+// GOOD — Context lets UserMenu read `user` directly; intermediates carry nothing extra
+function Page() {
+  return <Layout />;
+}
+
+function UserMenu() {
+  const { user } = useCurrentUser();
+  return <button>{user.name}</button>;
+}
+```
+
+When deciding between context, composition, or a store, see [state-management.md](state-management.md).
+
+## Defensive Memoization
+
+```tsx
+// BAD — memoizing trivial values
+const label = useMemo(() => `Hello, ${name}`, [name]);
+const handleClick = useCallback(() => setOpen(true), []);
+
+// GOOD — only memoize when there is a proven reason
+const label = `Hello, ${name}`;
+const handleClick = () => setOpen(true);
+```
+
+## State Synchronization Effects
+
+```tsx
+// BAD — syncing state with state
+const [search, setSearch] = useState("");
+const [filteredItems, setFilteredItems] = useState(items);
+
+useEffect(() => {
+  setFilteredItems(items.filter((i) => i.name.includes(search)));
+}, [search, items]);
+
+// GOOD — compute during render
+const filteredItems = items.filter((i) => i.name.includes(search));
+```
+
+## Hook Mini-Frameworks
+
+```tsx
+// BAD — over-engineered hook that re-implements a library
+function useDataFetcher<T>(url: string, options: FetcherOptions<T>) {
+  const [state, dispatch] = useReducer(fetcherReducer, initialState);
+  useEffect(() => {
+    // 50 lines of custom fetching, caching, retry logic...
+  }, [url, options]);
+  return state;
+}
+
+// GOOD — use TanStack Query
+const { data, isLoading, error } = useQuery({
+  queryKey: [url],
+  queryFn: () => fetch(url).then((r) => r.json()),
+  retry: 3,
+});
+```
+
+## Index as Key
+
+```tsx
+// BAD — unstable keys cause incorrect reconciliation
+{items.map((item, index) => (
+  <Item key={index} {...item} />
+))}
+
+// GOOD — stable, unique key
+{items.map((item) => (
+  <Item key={item.id} {...item} />
+))}
+```
+
+## Spreading Unknown Props onto DOM Elements
+
+```tsx
+// BAD — unknown props forwarded to DOM, React will warn
+function Card({ className, ...rest }: Record<string, unknown>) {
+  return <div className={className} {...rest} />;
+}
+
+// GOOD — explicit allowed props
+interface CardProps {
+  className?: string;
+  children: React.ReactNode;
+}
+function Card({ className, children }: CardProps) {
+  return <div className={className}>{children}</div>;
+}
+```
+
+## See Also
+
+- [`use-effect.md`](use-effect.md) — when useEffect is wrong
+- [`memoization.md`](memoization.md) — when memoization is wrong
+- [`state-management.md`](state-management.md) — state hierarchy
+- [`../examples/bad/`](../examples/bad/) — concrete anti-pattern examples