@baldurpan/create-ai-workflow 0.2.0

package/templates/standards/philosophy/readability.md

@@ -0,0 +1,87 @@
+# Readability
+
+## Core Rule
+
+Code is read far more than it is written. Optimize for the reader.
+
+## DO
+
+- Write short, focused files with a single primary responsibility
+- Prefer flat over deeply nested logic
+- Use early returns to reduce nesting
+- Keep function bodies short — if it doesn't fit on one screen, consider splitting
+- Express intent in names, not comments
+- Make control flow obvious
+
+## DO NOT
+
+- Write comments that explain what the code does (use a better name instead)
+- Chain more than 3–4 operations without an intermediate named variable
+- Use ternaries for non-trivial conditions
+- Nest ternaries
+- Write clever one-liners that require mental parsing
+
+## Comments
+
+Write a comment only when the **why** is non-obvious:
+- A hidden constraint or business rule
+- A workaround for a specific bug or browser quirk
+- A subtle invariant that would surprise a reader
+
+Do not write comments that describe what the code does. The code already says that.
+
+```ts
+// BAD: explains what
+// increment the counter
+count += 1;
+
+// GOOD: explains why
+// Safari fires the resize event on scroll — debounce to avoid layout thrash
+window.addEventListener("resize", debouncedResize);
+```
+
+## Control Flow
+
+Prefer:
+
+```ts
+// early return over nested if
+if (!user) return null;
+if (!user.isActive) return <Suspended />;
+
+return <Dashboard user={user} />;
+```
+
+Over:
+
+```ts
+if (user) {
+  if (user.isActive) {
+    return <Dashboard user={user} />;
+  } else {
+    return <Suspended />;
+  }
+}
+return null;
+```
+
+## Naming
+
+Names should make a reader's job easier:
+
+- `isLoading` not `loading` (boolean prefix)
+- `formatCurrency` not `format` (specific action)
+- `selectedUserId` not `id` (entity + role)
+- `InvoiceLineItemRow` not `Row` (full context)
+
+## PRIORITY
+
+```
+Obviousness > Brevity > Cleverness
+```
+
+## See Also
+
+- [`maintainability.md`](maintainability.md) — colocation, deletability
+- [`../typescript/naming.md`](../typescript/naming.md) — naming conventions
+- [`../react/component-design.md`](../react/component-design.md) — file size and decomposition signals

package/templates/standards/php/README.md

@@ -0,0 +1,62 @@
+# PHP Engineering Standards
+
+> **When to load these standards:** Only when the task is explicitly PHP. This repository's primary stack is TypeScript on Node.js. PHP is supported as a secondary track for the rare case where it's the right tool — typically internal tooling, CMS integrations, queue-driven workflows, or PHP-first ecosystems (Laravel/Symfony/Slim projects).
+>
+> **Do not suggest PHP** for a new project, a Node-friendly task, or a TypeScript codebase. If the user wants PHP, they will say so explicitly.
+
+---
+
+## Philosophy
+
+Modern PHP is not "sprinkle PHP into HTML templates." A modern PHP codebase is:
+
+- Strongly typed wherever possible
+- Layered with clear domain boundaries
+- Framework-agnostic at the domain layer
+- Built around dependency injection
+- Free of global state and magic-heavy abstractions
+- Testable by design
+- Explicit over convenient
+
+Treat PHP like C#, Kotlin, Java, or TypeScript backends — structured, typed, layered, observable.
+
+## Baseline for New PHP Projects
+
+- PHP 8.3+
+- `declare(strict_types=1);` in every file
+- PHPStan at level max
+- Pint or PHP-CS-Fixer for formatting
+- Pest or PHPUnit for tests
+- Dockerized dev environment
+- PostgreSQL (MySQL acceptable)
+- Redis (for cache + queues)
+- Structured logging
+- CI/CD from day one
+
+## Conditional Loading
+
+| If the task involves… | Load… |
+|---|---|
+| Any PHP task | [`rules.md`](rules.md), [`anti-patterns.md`](anti-patterns.md) |
+| Architecture / new module | [`architecture.md`](architecture.md) |
+| Testing | [`testing.md`](testing.md) |
+| Security | [`security.md`](security.md) |
+| Tooling setup (Composer, PHPStan, Pint, Pest, Rector) | [`tooling.md`](tooling.md) |
+| Framework choice or framework-specific patterns | [`frameworks.md`](frameworks.md) |
+
+## Cross-Cutting Topics (Reuse Main Repo)
+
+These concepts apply across languages — use the main repo's docs:
+
+| Topic | Doc |
+|---|---|
+| Logging, error monitoring, observability | [`../tooling/observability.md`](../tooling/observability.md) |
+| CI gating, PR sizing, squash merges | [`../tooling/ci.md`](../tooling/ci.md) |
+| API design (REST, errors, pagination) | [`../architecture/api-design.md`](../architecture/api-design.md) |
+| Refactoring discipline | [`../architecture/refactoring.md`](../architecture/refactoring.md) |
+| Date/time handling | [`../tooling/dates.md`](../tooling/dates.md) — use the PHP equivalent (`DateTimeImmutable`, Carbon, or Brick\DateTime) |
+| Dependency boundaries (in a modular monolith) | [`../architecture/dependency-boundaries.md`](../architecture/dependency-boundaries.md) |
+
+## Documentation Style
+
+Same as the rest of this repo: directive, concise, hierarchical, example-heavy. `## DO` / `## DO NOT` / `## PRIORITY` sections. No prose essays.

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

@@ -0,0 +1,259 @@
+# PHP Anti-Patterns
+
+## God Arrays
+
+```php
+// BAD — array as data contract; no type safety, no IDE help
+function processUser(array $user): void
+{
+    $email = $user['email'];        // typo risk, missing key risk
+    $name = $user['profile']['name']; // deep array access
+}
+
+// GOOD — DTO or value object
+function processUser(User $user): void
+{
+    $email = $user->email;
+    $name = $user->profile->name;
+}
+```
+
+## Static Singleton State
+
+```php
+// BAD — hidden global state, untestable
+class Settings
+{
+    private static array $values = [];
+
+    public static function get(string $key): mixed
+    {
+        return self::$values[$key] ?? null;
+    }
+}
+
+Settings::get('feature_flag.x');
+
+// GOOD — injected dependency
+final class SettingsService
+{
+    public function __construct(private readonly SettingsRepository $repo) {}
+
+    public function get(string $key): mixed
+    {
+        return $this->repo->find($key);
+    }
+}
+```
+
+## Service Locator / Facade Abuse in Business Code
+
+```php
+// BAD — hidden dependencies, harder to test, magic
+class OrderService
+{
+    public function process(Order $order): void
+    {
+        $payment = app(PaymentGateway::class);
+        $logger = resolve(Logger::class);
+        DB::transaction(function () use ($order) { /* ... */ });
+        Cache::forget("order:{$order->id}");
+    }
+}
+
+// GOOD — constructor injection
+final class OrderService
+{
+    public function __construct(
+        private readonly PaymentGateway $payments,
+        private readonly LoggerInterface $logger,
+        private readonly TransactionManager $transactions,
+        private readonly CacheInterface $cache,
+    ) {}
+}
+```
+
+## Generic "Manager" / "Helper" Classes
+
+```php
+// BAD — vague name, accumulates unrelated methods
+class UserManager
+{
+    public function get(int $id) { /* ... */ }
+    public function update(User $user) { /* ... */ }
+    public function sendWelcomeEmail(User $user) { /* ... */ }
+    public function exportToCsv(array $users) { /* ... */ }
+    // ...
+}
+
+// GOOD — focused services named by responsibility
+final class FindUserById { /* ... */ }
+final class UpdateUserProfile { /* ... */ }
+final class SendWelcomeEmail { /* ... */ }
+final class ExportUsersToCsv { /* ... */ }
+```
+
+## Fat Controllers / Fat Models
+
+```php
+// BAD — business logic in the controller
+class InvoiceController
+{
+    public function store(Request $request)
+    {
+        $data = $request->validate([/* ... */]);
+        $invoice = new Invoice($data);
+        $tax = $invoice->amount * 0.20;
+        $invoice->total = $invoice->amount + $tax;
+        $invoice->save();
+        Mail::to($invoice->customer->email)->send(new InvoiceCreatedMail($invoice));
+        Log::info("invoice.created", ['id' => $invoice->id]);
+        return response()->json($invoice);
+    }
+}
+
+// GOOD — controller delegates to an application handler
+final class CreateInvoiceController
+{
+    public function __construct(private readonly CreateInvoiceHandler $handler) {}
+
+    public function __invoke(CreateInvoiceRequest $request): JsonResponse
+    {
+        $invoice = $this->handler->handle(CreateInvoiceCommand::fromRequest($request));
+        return new JsonResponse(InvoiceResource::from($invoice), 201);
+    }
+}
+```
+
+## Trait Pyramids
+
+```php
+// BAD — traits stacking hidden behavior
+class UserService
+{
+    use HasCaching;
+    use HasLogging;
+    use HasEvents;
+    use HasValidation;
+    use HasNotifications;
+    use HasRetries;
+    // What does this class actually do? Where does behavior come from?
+}
+
+// GOOD — composition
+final class UserService
+{
+    public function __construct(
+        private readonly Cache $cache,
+        private readonly LoggerInterface $logger,
+        private readonly EventDispatcher $events,
+    ) {}
+}
+```
+
+Use traits only for genuinely cross-cutting *implementation details* — not for sharing business behavior.
+
+## Deep Inheritance
+
+```php
+// BAD — design smell
+abstract class BaseController { /* ... */ }
+abstract class ApiController extends BaseController { /* ... */ }
+abstract class VersionedController extends ApiController { /* ... */ }
+class UserController extends VersionedController { /* ... */ }
+
+// GOOD — composition, often via middleware or invoke handlers
+final class UserController
+{
+    public function __construct(
+        private readonly ApiResponseFactory $responses,
+        private readonly UserFinder $users,
+    ) {}
+}
+```
+
+## Exceptions for Control Flow
+
+```php
+// BAD — exception as a return value
+public function findUserByEmail(string $email): User
+{
+    $user = $this->db->find($email);
+    if (!$user) {
+        throw new NotFoundException();
+    }
+    return $user;
+}
+
+// In caller:
+try {
+    $user = $service->findUserByEmail($email);
+} catch (NotFoundException) {
+    return null; // expected case, not exceptional
+}
+
+// GOOD — nullable return for expected absence
+public function findUserByEmail(string $email): ?User
+{
+    return $this->db->find($email);
+}
+```
+
+Reserve exceptions for genuinely exceptional situations: infrastructure failure, invariant violation, security breach.
+
+## Mixed HTML/PHP
+
+```php
+<!-- BAD — PHP and HTML interleaved in business logic -->
+<?php
+$users = DB::query("SELECT * FROM users");
+foreach ($users as $u) {
+    if ($u->active) {
+        echo "<div>" . htmlspecialchars($u->name) . "</div>";
+    }
+}
+?>
+```
+
+Use a template engine (Blade, Twig) for HTML. Keep PHP business logic in classes. Better yet, render the frontend in a SPA or HTMX layer.
+
+## Ignoring Static Analysis
+
+```php
+// BAD — silently passing untyped data; PHPStan would catch this
+function calculate($data)
+{
+    return $data['amount'] * $data['tax_rate'];
+}
+
+// GOOD — typed and PHPStan-verifiable
+function calculate(InvoiceData $data): Money
+{
+    return $data->amount->multiply($data->taxRate);
+}
+```
+
+Without PHPStan at high levels, "modern PHP" is incomplete. See [`tooling.md`](tooling.md).
+
+## Generic CRUD Repositories
+
+See [`architecture.md`](architecture.md) for the full pattern. Short version:
+
+```php
+// BAD
+$user = $userRepository->find($id);
+$userRepository->save($user);
+
+// Just use the ORM directly for this:
+$user = User::find($id);
+$user->save();
+
+// Build a repository only when it expresses domain meaning:
+$subscribers = $userRepository->findActiveSubscribers();
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — the positive patterns
+- [`architecture.md`](architecture.md) — layers, DI, value objects
+- [`tooling.md`](tooling.md) — PHPStan to catch many of these automatically

package/templates/standards/php/architecture.md

@@ -0,0 +1,241 @@
+# PHP Architecture
+
+## Core Rules
+
+- Default to a **modular monolith** with domain-driven boundaries
+- Separate **Domain**, **Application**, **Infrastructure**, and **Presentation** layers
+- Domain layer never imports framework code
+- Use **constructor injection** for all dependencies — no service locators, no global helpers, no static singletons
+- Keep controllers and handlers thin
+
+## Project Structure
+
+### Standard (DDD-flavored)
+
+```
+src/
+  Domain/         ← business rules, entities, value objects, domain services
+  Application/    ← use case orchestration (commands, queries, handlers)
+  Infrastructure/ ← database, cache, external APIs, framework adapters
+  Presentation/   ← controllers, HTTP, validation, serialization
+config/
+bootstrap/
+public/
+storage/
+tests/
+```
+
+### Lightweight (smaller projects)
+
+```
+src/
+  Core/
+  Services/
+  Repositories/
+  Http/
+  Support/
+```
+
+Prefer clear boundaries over deep nesting. If you find yourself creating `src/Everything/Managers/Helpers/Utilities/Common/Shared/`, the architecture has become unclear.
+
+## Layer Responsibilities
+
+### Domain
+
+Contains the business model. Pure PHP. No framework imports.
+
+- Entities (`Order`, `Invoice`, `Subscription`)
+- Value objects (`Money`, `EmailAddress`)
+- Domain services (logic that doesn't naturally fit on an entity)
+- Domain events (`InvoicePaid`, `SubscriptionCancelled`)
+
+Must NOT depend on:
+- Frameworks (Laravel, Symfony)
+- HTTP
+- Databases
+- Redis
+- Queues
+- External APIs
+
+### Application
+
+Coordinates use cases. Thin orchestration.
+
+- Commands (`CreateInvoice`, `RefundOrder`) — write operations
+- Queries (`GetActiveSubscribers`) — read operations
+- Handlers (one per command/query)
+- Transactional boundaries
+
+The Application layer calls domain services and infrastructure adapters. It doesn't contain business logic itself.
+
+### Infrastructure
+
+Framework-aware glue.
+
+- Database access (Eloquent, Doctrine, raw PDO)
+- Cache (Redis adapters)
+- External API clients
+- Queue adapters
+- Email sender implementations
+- Framework integration (service providers, container bindings)
+
+### Presentation
+
+The edge.
+
+- Controllers (HTTP entry points)
+- Form requests / request DTOs
+- Response serialization
+- API resource transformers
+
+Keep controllers thin:
+
+```php
+final class CreateInvoiceController
+{
+    public function __construct(
+        private readonly CreateInvoiceHandler $handler,
+    ) {}
+
+    public function __invoke(CreateInvoiceRequest $request): JsonResponse
+    {
+        $invoice = $this->handler->handle(CreateInvoiceCommand::fromRequest($request));
+        return new JsonResponse(InvoiceResource::from($invoice), 201);
+    }
+}
+```
+
+## Dependency Injection
+
+### Constructor Injection (Preferred)
+
+```php
+final class OrderService
+{
+    public function __construct(
+        private readonly PaymentGateway $payments,
+        private readonly OrderRepository $orders,
+        private readonly EventDispatcher $events,
+    ) {}
+}
+```
+
+### Avoid
+
+- `app()`, `resolve()`, `Container::get()` inside business code (service locator)
+- Facades inside domain or application layers
+- `static` factory methods that reach into the container
+- Global helpers (`auth()`, `request()`, `now()`) in domain/application code
+
+Constructor injection makes dependencies explicit, testable, and substitutable.
+
+## Value Objects
+
+Wrap primitives that have rules or constraints:
+
+```php
+final readonly class EmailAddress
+{
+    public function __construct(public string $value)
+    {
+        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
+            throw new InvalidArgumentException("Invalid email: $value");
+        }
+    }
+
+    public function __toString(): string
+    {
+        return $this->value;
+    }
+}
+```
+
+The value object guarantees its invariants — once you hold one, you know it's valid.
+
+## DTOs
+
+For boundaries — HTTP requests, queue jobs, service-to-service calls:
+
+```php
+final readonly class CreateUserDTO
+{
+    public function __construct(
+        public string $name,
+        public EmailAddress $email,
+    ) {}
+}
+```
+
+DTOs are simple data carriers. They don't have business behavior. Methods are limited to construction (`fromRequest`, `fromArray`) and serialization (`toArray`).
+
+## Repositories
+
+Repositories are useful **only** when they encode domain meaning. Generic CRUD wrappers are not useful.
+
+```php
+// BAD — generic CRUD, mirrors ORM
+interface UserRepository
+{
+    public function find(int $id): ?User;
+    public function save(User $user): void;
+    public function delete(User $user): void;
+}
+
+// GOOD — domain-shaped queries
+interface UserRepository
+{
+    public function findActiveSubscribers(): UserCollection;
+    public function findByEmail(EmailAddress $email): ?User;
+    public function countNewThisMonth(): int;
+}
+```
+
+If a repository's methods read like an ORM, don't bother — use the ORM directly.
+
+## Async Processing
+
+Use queues for:
+- Email and notifications
+- Webhook dispatch
+- Image / video / file processing
+- AI jobs (inference, embedding pipelines)
+- Reports
+- Any long-running operation
+
+Common queue backends: Redis, RabbitMQ, SQS. Laravel Horizon provides excellent queue observability.
+
+Avoid synchronous HTTP chains for work that doesn't need to be inline.
+
+## Modular Monolith First
+
+A well-structured modular monolith outperforms poorly-managed microservices in almost every case.
+
+- Start as a single deployable
+- Enforce module boundaries internally
+- Extract a service only when there's a clear scaling or team-ownership reason
+
+See [`../architecture/refactoring.md`](../architecture/refactoring.md) — extraction is a refactor, not a fresh build.
+
+## DO NOT
+
+- Put business logic in routes or controllers
+- Make the domain layer depend on a framework
+- Reach for CQRS, event sourcing, or microservices because they "sound advanced"
+- Build deep inheritance chains (`BaseController → ApiController → VersionedController → UserController`)
+- Use traits to share business behavior — use composition
+
+## PRIORITY
+
+```
+Layered boundaries > Framework convenience
+Constructor injection > Service locator / globals
+Domain-shaped repositories > Generic CRUD wrappers
+Modular monolith > Premature microservices
+```
+
+## See Also
+
+- [`rules.md`](rules.md) — strict typing for the layered code
+- [`anti-patterns.md`](anti-patterns.md) — what breaks layered architecture
+- [`frameworks.md`](frameworks.md) — framework-specific guidance
+- [`../architecture/refactoring.md`](../architecture/refactoring.md) — extracting modules