laravel-spatie-event-sourcing

name

laravel-spatie-event-sourcing

description

Use this skill any time a user works with Laravel and event sourcing together — whether setting up spatie/laravel-event-sourcing for the first time, designing a new event-sourced domain (aggregates, events, projectors, reactors), generating code for bounded contexts, or debugging issues with AggregateRoot, StoredEvent, or projectors. Trigger on: "event sourcing" + "Laravel", spatie ES references, requests to model domain lifecycles as events, or questions about aggregate roots and projectors in PHP/Laravel. Do NOT use for: refactoring existing CRUD into ES, Laravel's built-in Event::dispatch system, CQRS without event sourcing, or non-spatie packages.

Laravel Spatie Event Sourcing — Skill

Generate event-sourced domain code for Laravel using spatie/laravel-event-sourcing, following a two-gate workflow: Design first, then implement with tests.

Quick reference

• references/design-heuristics.md — Event naming, aggregate boundaries, projector/reactor rules, anti-patterns
• references/adr-template.md — ADR template for Gate 1
• references/tdd-patterns.md — Pest and PHPUnit test patterns
• references/commands-pattern.md — Command + handler patterns (plain and bus-dispatched)
• references/spatie-api-cheatsheet.md — Key Spatie ES classes and methods
• assets/templates/*.stub — Code generation stubs

Project bootstrap (one-time, automatic)

On first invocation in a project, run scripts/verify-setup.sh from this skill's directory. It checks:

0. PHP 8.2+ is installed (required by spatie/laravel-event-sourcing v7)
1. spatie/laravel-event-sourcing is in composer.json
2. The stored_events and snapshots tables exist (migrations have run)
3. config/event-sourcing.php has been published
4. A test framework is installed (Pest preferred, PHPUnit fallback)

If anything is missing, print the single command that fixes it and stop. Do not auto-install packages or run migrations on behalf of the user — they need to confirm first.

If everything passes, check for .claude/event-sourcing.md in the project root. If it doesn't exist, ask the user one configuration question:

"I'll create a project config at .claude/event-sourcing.md. Two quick choices:

1. Command dispatch style: plain handler classes invoked directly, or Laravel's command bus (Bus::dispatch)?
2. Test framework: Pest or PHPUnit?"

Write their answers to that file. On future invocations, read it silently and proceed.

---

The two-gate workflow

This skill operates in two gates with a hard stop between them. The user must approve the design before any code gets written.

Gate 1 — Design (ADR)

Start with domain analysis. Ask 3–5 focused questions (skip any the user already answered):

1. What feature or bounded context are we building? (one sentence)
2. What state does it hold, and what state transitions matter?
3. What external actions trigger those transitions?
4. What read models does the application need?
5. What side effects happen on state changes? (emails, external API calls, other aggregates)

Then produce an ADR using the template in references/adr-template.md. The ADR covers:

• Proposed aggregate(s) with justification for each boundary
• Commands that trigger each aggregate method
• Events recorded by each method (past-tense, domain-meaningful names — read references/design-heuristics.md for naming rules)
• Projectors and their read models (sync vs queued, with reasoning)
• Reactors and their side effects
• Invariants the aggregate enforces
• Explicitly punted concerns (data migration, snapshots, etc.)
• Anti-patterns actively avoided

Stop here. Present the ADR and wait for the user to approve, request changes, or edit inline. Iterate until they say something like "approved", "looks good", or "let's build it."

Do not write any implementation code during Gate 1.

Gate 2 — Implementation + verification

Once the ADR is approved, generate everything in one uninterrupted flow. No mid-implementation questions — if something is ambiguous, that's an ADR defect; go back to Gate 1.

Generation order:

1. Create the directory structure under app/Domain/<Context>/
2. Write tests FIRST (Pest or PHPUnit per project config) — aggregate tests, projector tests, reactor tests
3. Write command DTOs
4. Write command handlers (plain or bus-dispatched per project config)
5. Write the aggregate root
6. Write event classes
7. Write projector(s) and read-model migration(s) — migrations must use a UUID primary key ($table->uuid('uuid')->primary()), no auto-increment, and include $table->timestamps()
8. Write reactor(s)
9. Register projectors and reactors in config/event-sourcing.php
10. Run the test suite (./vendor/bin/pest or ./vendor/bin/phpunit)
11. Report: list of files created + test output

Use the stub templates in assets/templates/ as starting points. Read references/tdd-patterns.md for test structure and references/commands-pattern.md for command/handler patterns.

Stop here. Present the results. The user approves, requests changes, or moves to the next feature.

Directory conventions

app/Domain/<Context>/
├── Aggregates/
│   └── <Name>Aggregate.php
├── Commands/
│   └── <Verb><Noun>Command.php
├── CommandHandlers/
│   └── <Verb><Noun>Handler.php
├── Events/
│   └── <Noun><PastTenseVerb>.php
├── Projectors/
│   └── <Noun>Projector.php
├── Reactors/
│   └── Send<Noun><Action>Reactor.php
└── ReadModels/
    └── <Noun>.php

tests/Feature/<Context>/
├── <Name>AggregateTest.php
├── <Noun>ProjectorTest.php
└── <Noun>ReactorTest.php

database/migrations/
└── <timestamp>_create_<read_model>_table.php

Scope boundary

This skill is for greenfield event sourcing only. If the user asks to refactor existing CRUD code into event sourcing, politely decline and explain that CRUD-to-ES migration is a different (and much harder) problem that this skill doesn't cover. Suggest they design the event-sourced version from scratch alongside the existing code instead.

When things go wrong

• Tests fail after generation: Read the failure output, fix the code, rerun. Don't ask the user to debug generated code — that's our job.
• Ambiguity during Gate 2: Return to Gate 1 and update the ADR. Don't make assumptions mid-implementation.
• User wants to change the design after seeing code: No problem — update the ADR, regenerate the affected files, rerun tests.