DEV Community: Alberto Arena

My coding agent kept inventing columns

Alberto Arena — Mon, 10 Aug 2026 14:30:52 +0000

Ask a coding agent to write a query against a table it hasn't seen this session, and it will guess. Confidently, plausibly, and wrong: a foreign key named author_id when the column is actually created_by, a status treated as a free-text string when it's a tinyint enum, a table it's sure exists because a table like it usually does. It isn't lying, it just doesn't know, and nothing forces it to say so.

The usual fix is pasting a schema dump into the chat at the start of a session. That works until the next migration, at which point it's just a different kind of wrong: confidently out of date instead of confidently invented.

There's an obvious third option: let the agent run queries itself, most coding agents can already execute SQL. But that means handing over real database credentials, and a connection that can query can also see rows, not just structure. That's a bigger grant than the problem needs.

Truss has always been a live, zoomable ER diagram of your Laravel app's real database schema, structure only, never a row of data. Version 1.8 points that same live structure at a coding agent instead of a browser tab.

Give it meaning a type can't carry

A column tells an agent its name and type, not what it means. status = 1 doesn't say "paid" on its own. Annotate it once and every export carries it:

// config/truss.php
'annotations' => [
    'source' => ['config', 'database'],
    'tables' => [
        'orders' => [
            'note' => 'One row per checkout attempt, not per completed order.',
            'columns' => [
                'status' => 'tinyint: 0 pending, 1 paid, 2 refunded',
            ],
        ],
    ],
],

If your database already carries COMMENT strings on tables and columns, leave 'database' in annotations.source and Truss reads those directly, no duplicate config to keep in sync. Either way, a comment is part of the CREATE TABLE definition, not a row: still structure only. Strip them from any single export with --no-annotations when you just want the bare shape.

Trim it to what the question needs

A forty-table schema is a lot of tokens to spend on a question about one table. --compact drops column defaults and non-unique indexes without dropping a single table, column, or foreign key. --focus=orders --depth=1 narrows the export to one table and its foreign-key neighbourhood, the same idea as the dashboard's focus mode, now available from the command line. And there's a new llm format alongside the existing five (DBML, JSON, CSV, Markdown, Mermaid), a dense plaintext export tuned for a token budget rather than for a human reading a data dictionary:

php artisan truss:export --format=llm --focus=orders --depth=1 --compact

That's what the export produces. Calling it is just as direct, in code or over HTTP.

Building the same thing in code goes through a new fluent, immutable Truss facade instead of the command:

Truss::snapshot()->focus('orders', depth: 1)->compact()->toDbml();

And a gated GET {prefix}/export/{format} route serves the identical output to any HTTP client, behind the same viewTruss gate as the dashboard. Command, facade, route, dashboard download: one pipeline underneath all four, so they can never quietly disagree with each other.

Ask it live, instead of pasting a snapshot

The part I actually wanted, though, wasn't a better export. It was not exporting anything at all.

Truss 1.8 adds an optional server for MCP, the Model Context Protocol that Claude Code, Claude Desktop, and Cursor use to reach outside tools. Built on laravel/mcp, it talks to a coding agent directly over local stdio:

composer require laravel/mcp
php artisan mcp:start truss

Point one at it and the agent gets five tools, list_tables, describe_table, get_schema, focus_table, and get_structural_review, plus a truss://schema resource, all reading the live schema on demand. Every tool advertises MCP's readOnlyHint, so a client can present them as read-only instead of prompting for write approval on a call that was never going to write anything. No row data, ever, and the same exclusion and managed-connection safeguards as the rest of Truss apply here too, opt-in and off by default behind truss.mcp.enabled.

I pointed it at a real project I've worked on for a while, in Claude Desktop, and the difference was immediate: instead of me pasting a schema dump at the start of the conversation, or the agent asking me to run a query to check a column name, it just called describe_table before it wrote anything, the same check that would have caught the guessed author_id from the start of this post. No staleness, because there's nothing to go stale, it's reading the same live introspection the diagram uses.

Try it

Live demo, running against a fictional schema
AI context guide: trussphp.com/guides/ai-context
MCP server guide: trussphp.com/guides/mcp-server
Full changelog: CHANGELOG.md on GitHub

Update with composer update albertoarena/laravel-truss, and if you want the MCP server too, composer require laravel/mcp on top.

What's next

More truss:doctor rules and CI-native output formats are next on the roadmap, followed by reading Eloquent relationships for semantic edge labels instead of raw foreign keys, and navigation aids for schemas with a hundred tables or more. If a tool the agent needs isn't there yet, or an annotation source you'd want isn't supported, open a discussion.

Claude Code Auto Mode: What Still Needs a Human

Alberto Arena — Mon, 10 Aug 2026 08:43:01 +0000

Starting August 14, auto mode becomes the default permission mode for Claude Code on Pro, Max, and Team plans. Buried in Anthropic's own announcement is a number worth sitting with: in a controlled test with 1,053 paid professional testers, researchers swapped in genuinely dangerous commands partway through real sessions. Humans caught 13.6% of them. Auto mode's classifier caught 89%.

That's not a subtle gap, and reading it made me a little uncomfortable, because I've spent most of the last few months running my own sessions in accept-edits or auto mode, clicking through permission prompts the same way everyone apparently does. Anthropic's own usage data backs that up: people approve 97% of ordinary permission prompts, and the rate at which someone actually catches a dangerous one degrades from roughly 17% early in a session to about 5% after fifty-plus prior approvals. We're not reading carefully. We're pattern-matching on "this looks like the last forty things I clicked yes on," and that pattern breaks exactly when it stops holding.

	Human review	Auto mode classifier
Dangerous commands caught (1,053-tester study)	13.6%	89%
Production-severity unintended harm, real flagged sessions	6.3%	2.4%

The second row comes from Anthropic's audit of real, already-flagged sessions rather than a lab test: manually-approved sessions contained serious unintended harm more than twice as often as auto mode sessions did. Different methodology, same direction.

What actually changes on August 14

Auto mode itself is a fairly simple change to the default flow. Right now, Claude pauses before most file edits and shell commands and waits for you to click approve. Under auto mode, it doesn't. Instead, a separate classifier model reviews each action in the background as Claude proposes it, and only interrupts you when it judges something risky: an irreversible action, a request that escalates beyond what you asked for, an attempt to send data somewhere it shouldn't go. Everything else, the reads, the routine edits, the ordinary shell commands, runs without a prompt at all.

The classifier sits underneath the permission mode you've already picked, not instead of it. Your allow, ask, and deny rules resolve first; the classifier only gets a say on whatever those rules don't already settle. That layering is exactly what makes the rest of this post possible: the classifier isn't the only thing standing between Claude and a bad command, it's the last one, and everything upstream of it is something you configure.

The asterisk Anthropic puts on its own number

None of this means auto mode is safe, and Anthropic doesn't claim it is. Their own line: "auto mode relies on classification systems and therefore does not eliminate risk." They ran a two-week red-teaming pilot with Apollo Research, injecting synthetic attacks into real workflows. Before the hardening that shipped with this release, the classifier missed 12% of those attacks. After hardening, 7%, on a test set the classifier had never seen during tuning. Better than a distracted human. Not zero.

What the classifier is actually built to catch is specific: scope escalation on a vague or destructive request, credential exploration, exfiltration through an external service like a public gist, retrying a failed deploy with a skip-verification flag, a command that reads normally but was seeded by hostile content Claude picked up along the way. Where it still misses isn't usually "is this dangerous", it correctly flags danger most of the time. It's "does a real consent signal in this session actually cover this specific action", the same ambiguity a tired human glosses over, just less often.

So the useful question isn't auto mode versus manual review. It's what to put alongside auto mode that fails in a different way than auto mode does.

Rules that hold no matter the mode

The classifier isn't the only layer available, and it's not the one you have the most control over. Permission rules sit underneath it: the docs are explicit that "these controls apply in every mode, including bypassPermissions: deny rules and explicit ask rules." Deny is a hard stop the classifier never gets to weigh in on. Ask still forces a prompt, even in a mode whose entire point is skipping prompts, which matters because the example below relies on it.

Here's a concrete gap worth knowing about: auto mode auto-approves pushes to any branch of the repository you're working in, including the default branch, unless you tell it otherwise. The classifier judges the push's content on its own terms, but the act of pushing to main isn't itself something it blocks by default. If you want that to always stop for a human, write it down:

{
  "permissions": {
    "ask": [
      "Bash(git push origin main)",
      "Bash(git push origin master)"
    ]
  }
}

The push example above uses ask on purpose: you still want to push eventually, just with a human in the loop first. That's different from an invariant you never want crossed at all, "no data exposed, ever," say, in a CLAUDE.md file. A rules file states that kind of invariant as a request Claude tries to honor. A deny rule enforces it: a request the tool can't route around, in any mode, on any day you forget you're in auto mode at all.

A gate automation can't talk itself out of

Rules cover what you can name in advance. Hooks cover what you want checked every time, mechanically, regardless of what the classifier decides. A PreToolUse hook can inspect a tool call before it runs and block it outright, deterministically, with no probability involved:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git push *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-green-tests.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# .claude/hooks/require-green-tests.sh
if ! npm test --silent; then
  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"Tests are red, push blocked"}}'
else
  exit 0
fi

The if field narrows this to git push calls specifically, the script runs the test suite, and a failing suite returns a deny decision that blocks the push outright, exit code 2 works the same way with a plain stderr message. Nothing here asks a classifier to judge intent. It's a yes/no gate on a fact you can check.

Review moves, it doesn't disappear

None of the above replaces reading the diff. It changes what "reading the diff" is for. I wrote before about how agentic development turned most of the job into review, and the failure mode there isn't that people stopped reviewing, it's that review quality degrades under volume exactly the way the approval-fatigue numbers above describe. Auto mode doesn't fix that. It just removes the low-value prompts so the review that's left can, in theory, be the kind that actually catches something.

In practice that means picking one point in the loop where you deliberately stay the bottleneck, on purpose, and the push to a shared branch is the obvious candidate. It's the one action that's genuinely hard to undo and visible to someone else the moment it happens. Everything upstream of that, a wrong edit, a bad approach, a half-finished refactor, is still local and still reversible. Hallucinated code compiles and passes a quick glance; it doesn't survive someone actually reading it against what they asked for. That reading has to happen somewhere. Put it at the boundary that matters and let the classifier and the hooks handle the volume everywhere else.

Tests are the check that doesn't get tired

The hook above only works because there's a test suite behind it. That's the other half of the strategy: tests are the executable version of "did this actually do what I asked", and unlike a human on prompt four hundred of a session, they don't get less careful over time. Write them before or alongside the change, not after, and the git push gate above stops being a formality and starts being the thing that actually catches a regression a tired reviewer would have waved through.

Stacking checks that fail differently

None of this makes the miss rate zero, same as auto mode itself doesn't. The point isn't finding the one control that eliminates risk. It's stacking controls that fail in different ways, so the same blind spot doesn't line up twice. The classifier catches the obvious and the fast. Deny rules catch the specific thing you already know matters. Hooks catch what you can specify as a check. Tests catch what you can assert. And a deliberate human read at the point something becomes shared catches the one thing none of the above can judge: whether this was the right thing to build in the first place.

Thirteen point six percent is a bad number for humans working alone. Eighty-nine percent is a good number for a classifier working alone. Neither one is the number that matters. The number that matters is what's left over once you've stacked both, plus the checks that are actually yours to configure.

Sources

Auto mode is now the default in Claude Code for Pro, Max, and Team plans: the announcement this post responds to, including the 1,053-tester study and the real-session audit numbers.
How we built Claude Code auto mode: a safer way to skip permissions: the technical writeup covering the classifier's two-stage design and what it's built to catch.
Choose a permission mode: official documentation on default, acceptEdits, bypassPermissions, and how permission rules interact with each mode.
Hooks reference: official documentation on hook events, matcher syntax, and the PreToolUse block/allow contract used in the example above.

I built a Laravel event-sourcing generator, then the AI version

Alberto Arena — Thu, 06 Aug 2026 06:01:00 +0000

A while back I built a code generator for event sourcing in Laravel: run one artisan command against spatie/laravel-event-sourcing, get aggregates, events, projectors, and reactors scaffolded out. It's deterministic. Same inputs, same output, every time. It just crossed 10,000 downloads on Packagist.

More recently I built a Claude Code skill that produces the same kind of domain code, except it starts with a conversation instead of a command. So the question people keep sending me is obvious: does the AI skill replace the generator?

No. And the reason is more interesting than the question.

The short version, if you skip everything else: AI didn't kill the code generator. It took over the design half of the job and left the deterministic half exactly where determinism still matters.

What the generator is good at

The generator's whole value proposition is determinism. composer require albertoarena/laravel-event-sourcing-generator, then php artisan make:event-sourcing-domain Order, and you get exactly the files you'd expect, byte-identical every run. No tokens, no API key, no network dependency, nothing to review for "did it hallucinate a method." It runs the same in CI as it does on my laptop.

That's exactly right when I already know the shape of the domain: I know the aggregate boundary, I know the events, I just need the boilerplate written consistently. What it can't do is help me figure out whether that boundary is correct in the first place. It assumes I already did the hard part.

What the skill is good at

The skill is not a code generator wearing an AI costume. Its value sits upstream of the code, in a two-gate workflow:

Gate 1, design. It asks focused questions about the domain and produces an Architecture Decision Record: aggregates, commands, events, projectors, reactors, and the invariants holding them together. Nothing gets written until I approve that ADR.
Gate 2, implementation. Once I approve it, it writes tests first, then generates the full domain, and runs the suite. For that cancel-after-ship rule, that means a test asserting the aggregate throws before a line of the aggregate itself exists, not after.

The part that actually matters is Gate 1. "Can cancel still fire after ship?" is a modelling question, and that's the conversation where event sourcing lives or dies. The generator was never going to have that conversation with me. It doesn't ask questions; it executes a decision I've already made.

The real dividing line

Both tools end up emitting similar-looking PHP, which is why people fixate on the overlap. But codegen is the least interesting thing either one does. The line that actually matters is this:

I already know the design → the generator. Deterministic, fast, no review tax, no dependency on an LLM being available or correct.
I'm still figuring out the design → the skill. It's a modelling partner that leaves a paper trail (the ADR) and a safety net (tests written before the implementation exists).

Which one I actually reach for

Honestly, mostly the skill these days. Most of the time I sit down to add a new bounded context, the boundary isn't fully settled yet, and paying for a five-minute design conversation before anything gets written is worth more than skipping straight to boilerplate. The ADR forces me to answer the awkward "wait, should that be an event or a side effect?" questions before they turn into a rewrite.

That doesn't mean the generator's properties stopped mattering. It still gets pulled out whenever the reasons I built it in the first place are the reasons that matter: expanding a domain whose shape is already locked in, running in a pipeline where I don't want an LLM in the loop, or anywhere determinism and zero token cost outrank a design conversation I don't need to have again. I just don't hit that situation as often as I used to, now that the skill exists.

Where I don't use the skill at all

Being upfront about the edges is the point of writing this. The skill is greenfield only. It designs new event-sourced domains; it does not refactor existing CRUD into event sourcing, and it's scoped specifically to spatie/laravel-event-sourcing v7, not Laravel's own event system, not CQRS without event sourcing, not other packages. If that's your situation, neither tool here is the answer, and I'd rather say so than sell you a mismatch.

Try either

If you're modelling a new event-sourced domain and Claude Code is already part of your workflow, the skill installs in two steps: the first points Claude Code at the marketplace (nothing installs yet), the second installs the plugin from it.

/plugin marketplace add albertoarena/claude-laravel-event-sourcing
/plugin install laravel-spatie-event-sourcing@albertoarena

If you already know the shape of the domain and just want the boilerplate, the generator is a Composer install away:

composer require albertoarena/laravel-event-sourcing-generator
php artisan make:event-sourcing-domain Order

Full write-ups of each, if you want the mechanics: the generator, the skill, and the original walkthrough of building a domain with Spatie event sourcing if you're new to any of this.

I gave my schema viewer your app's colours

Alberto Arena — Tue, 04 Aug 2026 11:25:25 +0000

Truss is a live, zoomable ER diagram of your Laravel app's actual database schema, safe to run in production because it only ever reads structure. I introduced it back in July, and it's been part of every client project since, gated behind a viewTruss policy. Two things kept nagging at me. The dashboard was always Truss blue, whatever the client's actual brand was, so it looked bolted onto their app rather than part of it. And the export button, one click for a Markdown data dictionary or a DBML file, only ever got clicked when I remembered to, so the schema file committed to the repo drifted quietly from the real one until someone noticed, usually the hard way.

Truss 1.6 fixes both: a themeable dashboard that matches whatever it's embedded in, and a truss:export command that puts the same output in your terminal and your CI pipeline, no browser required.

Match it to your app

Colours and fonts now live under truss.theme in config, and Truss re-skins itself in both light and dark mode:

// config/truss.php
'theme' => [
    'colors' => [
        'light' => [
            'accent' => '#b45309',
            'accent-secondary' => '#0f766e',
            'background' => '#faf6f0',
            'surface' => '#fffdf8',
            'text' => '#3a2a1c',
            'border' => '#c8873f',
        ],
        'dark' => [
            'accent' => '#fbbf24',
            'background' => '#1b130b',
            'surface' => '#26190d',
            'text' => '#f5e6d0',
            'border' => '#8a6428',
        ],
    ],
],

Only the knobs you set are overridden, everything else stays on the default Blueprint palette, so three or four values are enough to make it look at home. The re-skin runs deep: the diagram's relationship lines, label backdrops, background grid, table rows, and inputs all follow, not just the toolbar chrome. It ships as a same-origin stylesheet, no build step, style-src 'self' still covers it, and a default install adds no extra request at all. Each value is validated before it's written, so a typo falls back to the default instead of breaking the sheet.

Picking hex values by hand isn't required. The new theme builder previews a palette against the real dashboard live, starts from presets (Blueprint, Ember, Contrast) if you'd rather tweak than start blank, and generates the exact config/truss.php snippet to paste in.

Get a schema file without opening a browser

php artisan truss:export --format=dbml --output=docs/schema.dbml
php artisan truss:export --format=json --check

truss:export is the export button's command-line counterpart: the same five formats (DBML, JSON, CSV, Markdown data dictionary, Mermaid), generated straight from PHP, no browser involved. Output is deterministic, the same schema always produces the same bytes, which is what makes --check worth running: point it at the file you've committed, and it exits 1 the moment that file stops matching the database, 2 on a usage error, 0 when everything lines up. Wire it into a commit hook or CI, and schema drift stops being something a reviewer has to notice by eye. Structure only, as always, no network call.

Try it

Theme builder: trussphp.com/theme-builder
Live demo: trussphp.com/demo
Theming guide: trussphp.com/guides/theming
Schema export guide: trussphp.com/guides/schema-export
Release notes: v1.6.0 on GitHub

Update with composer update albertoarena/laravel-truss.

What's next

Lighthouse CI is next on the roadmap: automated performance and accessibility audits across both themes, light and dark. After that: more truss:doctor rules, reading Eloquent relationships for semantic labels instead of just foreign keys, and schema context formatted for AI agents working in the same codebase. If a theme knob is missing or truss:export should support a format it doesn't, open a discussion.

We Became Editors-in-Chief, and Nobody Trained Us

Alberto Arena — Mon, 03 Aug 2026 06:13:59 +0000

Most of my working day now looks like this: I write a prompt describing what I want. An agent produces a diff. I read it, and either approve it or ask for a refinement. Repeat, dozens of times, until the feature is done.

Ask whether that makes us "prompt engineers" and you're asking the wrong question. Prompt wording is a thin skill, learnable in an afternoon. What's actually changed, after twenty-seven years of writing code the old way, is what the job does to your attention. Less typing. Much more reviewing, at a volume and pace nothing in my career prepared me for.

The loop, honestly described

Strip away the branding and agentic development is a review cycle. You describe an outcome. The agent proposes an implementation. You check it against a mental model of what "correct" means for this codebase, this edge case, this architecture, and you either accept it or push back with more context.

That's not a new activity. It's code review, except the author on the other side never gets tired, never pushes back, and produces a plausible-looking diff in seconds whether it's right or not. The volume changes everything. When review is the bottleneck instead of typing, the job's centre of gravity moves with it.

A different kind of tired

The old way was stressful in bursts. You'd hit a bug, lose an afternoon to it, feel the specific frustration of a stack trace that refuses to make sense. Stressful, but the pace was yours. Typing is slow. Debugging forces pauses. Whether you wanted it or not, there was slack built into the rhythm.

Agentic coding removes that slack. The agent doesn't pace itself to your attention span. It just keeps producing diffs, one after another, faster than you'd ever type them yourself. To review well you need prolonged, focused attention, held at a level that used to only show up during the hard parts. There's no natural lull left for your brain to reset in, because generation never slows down to let you catch up. A whole afternoon of that is a different kind of tired than a whole afternoon spent stuck on one stubborn bug, and after twenty-seven years of the old rhythm, this one still catches me off guard some days.

"Prompt engineer" is the wrong name for it

The skill that matters here was never prompt wording. It's knowing what correct looks like before you see the diff: why a query needs an index, why a migration is unsafe under concurrent writes, why a "working" abstraction will hurt in six months. That judgment doesn't come from prompting practice. It comes from having built things, broken things, and paid for the mistakes.

The people getting the most out of agentic tools right now aren't the ones with the cleverest prompts. They're the ones who can look at generated code and immediately spot the one line that's subtly wrong, because they've written that exact bug themselves at some point. Prompting is the interface. Engineering judgment is still the job.

Where this goes in five years

Three things seem likely to me, in no particular order of confidence.

Review becomes the skill we train for, not the one we tolerate. Right now most of us learned to review code as a secondary skill, something you did after learning to write it. If specifying and judging becomes the primary loop, reviewing well, fast and without rubber-stamping, has to become something we deliberately get better at, the way we once deliberately got better at algorithms.

We start designing around reviewer fatigue, not just reviewer speed. Right now most tooling optimises for how fast an agent can produce a diff. The actual constraint is how long a human can sustain high-attention review before quality drops. I'd expect smaller, more frequent checkpoints, better summaries of what changed and why before you dive into the diff itself, and more deliberate pacing, because burning out the reviewer is now the real bottleneck, not the code generation.

The gap between good and bad engineers widens, not narrows. Agentic tools are a multiplier, and multipliers amplify what's already there. An engineer with strong judgment reviews faster and catches more. An engineer without it approves more bugs, faster than before. The floor for "can produce working code" drops. The ceiling for "can be trusted to ship it" doesn't move, or gets more valuable precisely because it's rarer.

The part I'm less sure about

What worries me isn't the loop itself: it's whether the judgment that makes the loop work survives if fewer people spend years building it the hard way. Review is only as good as the model you're reviewing against, and that model used to be built by writing thousands of lines yourself, badly, and fixing them. If the next generation of engineers reviews before it ever really writes, I don't know yet whether that produces the same instincts faster, or a generation of reviewers who can't tell a plausible diff from a correct one.

So no, I don't think we're becoming prompt engineers. I think we're becoming editors-in-chief of our own code, and editing well is its own craft, one most of us are still learning on the job. Where that leaves the next five years is the part I'm genuinely curious about, not the part I have a tidy answer for.

Originally published on albertoarena.it

The schema doctor is in

Alberto Arena — Fri, 31 Jul 2026 05:05:07 +0000

A migration that adds a user_id column with no supporting index passes review every time. It looks fine. Laravel doesn't complain, the migration runs clean, CI is green. Then a few months later someone's staring at a JOIN that touches two hundred rows and takes eight seconds, and nobody remembers why.

That's the class of problem Truss 1.5 is built to catch before it ships: the schema doctor.

I wrote about Truss here in July, a live, zoomable ER diagram of your Laravel app's actual database schema. It's picked up more traction than I expected since then: it's closing in on 300 installs on Packagist and past 70 stars on GitHub, almost entirely word of mouth in the Laravel community. That traction is exactly what pushed the next feature: a diagram is great for seeing your schema, but it doesn't tell you when something in it is wrong. truss:doctor does.

What it catches

Run it and it flags problems that are visible from structure alone:

Tables with no primary key
Foreign keys with no supporting index
Duplicate or redundant indexes
Foreign keys whose type doesn't match the key they reference
Money-looking columns stored as float
Pivots without a unique key, unindexed deleted_at, and more

Thirteen rules in total, across integrity, index, and type categories, each with a stable code (like TRUSS-IDX-001) so you can look it up, silence it, or change its severity.

Rules are engine-aware where it matters: an unindexed foreign key is an error on PostgreSQL and SQLite, but only info on MySQL and MariaDB, since those auto-index foreign keys.

In the terminal and CI

php artisan truss:doctor
php artisan truss:doctor --preset=strict --fail-on=warning
php artisan truss:doctor --format=json

It exits non-zero once a finding hits your fail level, so a migration that introduces a problem fails the build. No AI, no queries, no row data: deterministic and structure-only, safe to run in a commit hook or a CI pipeline against a database you don't fully trust.

In the dashboard

The same findings surface in the dashboard as a new Health panel, the heart icon in the toolbar. Tables with a problem are flagged right on the diagram, the offending column is marked inline, and lower-confidence (heuristic) findings are labelled as such. Same engine, same findings, two front ends depending on whether you're at a terminal or in the browser.

Try it

The live demo has it running against a fictional schema. Open the Health panel and you'll see a handful of foreign keys flagged for a missing index.

Live demo: trussphp.com/demo
Guide, with every rule code: trussphp.com/guides/schema-doctor
Release notes: v1.5.0 on GitHub

Update with composer update albertoarena/laravel-truss, then run php artisan truss:doctor and see what's already in there.

What's next

This is phase one: the engine and the thirteen rules. Suppression files, more rules, and CI formatters are on the roadmap. If a rule feels too noisy, too quiet, or there's a check you'd want that isn't there yet, the discussion thread is open. I'd love to hear what you run it against.

CLAUDE.md Is RAM, Skills Are Not Disk: The Four-Tier Memory Model for Claude Code

Alberto Arena — Mon, 27 Jul 2026 10:30:21 +0000

Claude Code loads CLAUDE.md in full at the start of every session and keeps it resident the whole time, so every line in it is a line you pay for on every turn, whether the task in front of you needs it or not. CLAUDE.md Is RAM, Not Disk split that into two tiers to deal with it: CLAUDE.md holds only what Claude needs every time, stack, commands, invariants; everything else moves to docs/, which loads only when something points Claude there. Working memory stays small and constantly paid for. Long-term memory stays cheap because it's optional.

I wasn't using custom skills when I wrote that post. Once I started, the obvious move was to file them under disk too: they're detail Claude doesn't need every turn, so surely they belong wherever the rest of the on-demand material lives. That reasoning is wrong, and it took checking how skills actually behave in context to see why. A skill is not a document Claude opens when curious. It's closer to a program that gets launched, and treating it like disk is how invariants end up sitting behind a trigger that might not fire.

Here's the model with two more tiers than it had before: CLAUDE.md is RAM, path-scoped rules are demand-paged RAM, skills are installed programs, and docs/ is disk. Each tier answers the same question differently: when does this load, and what happens to it after. Get that question right for a given piece of instruction and the tier picks itself.

Checked against Claude Code v2.1.212 on July 27, 2026. The listing and compaction budgets below are the kind of number that moves; verify them against the current docs before leaning on the exact figures.

What the two-tier model couldn't see

The original test was: does Claude need this every turn, or only sometimes? That question sorts CLAUDE.md from docs/ correctly, but it quietly assumes there are only two ways for something to load: resident from the start, or resident only once Claude decides to open a file. Path-scoped rules and skills both load conditionally, and neither one is "Claude decides to open a file."

A rule loads because a file path matched a glob. That's deterministic, the same way session start is deterministic, just scoped instead of constant. A skill loads because Claude matched a task description to a name in a list. That's probabilistic: it matches text, so it usually fires and sometimes does not. Collapsing those two into "sometimes" and filing both next to docs/ erases the one distinction that actually matters: whether the content is guaranteed to show up when you need it, or merely likely to.

Tier 1: RAM, unchanged

CLAUDE.md still works exactly the way the first post described it: loaded in full at session start, resident every turn after, re-read from disk and re-injected after /compact. Adding three more tiers doesn't change what belongs here, stack, commands, the handful of invariants that must never break. It's still the only tier with no "when does this load" question to answer. The answer is always.

Tier 2: demand-paged RAM, and a correction to the first post

The nested CLAUDE.md trick from the original post still works, but there's a cleaner mechanism for the same job. If you copied that trick into your own project, this is the point where I'd tell you to migrate it. .claude/rules/*.md files with a paths: glob in their frontmatter load into context the same way a nested CLAUDE.md does, when Claude reads a file that matches. The docs say a nested CLAUDE.md is not re-injected after /compact and reloads the next time Claude touches that subdirectory. They don't say the same for rules, and my own testing suggests it behaves the same way.

Leave off paths: and none of this applies. A rule file without it loads at launch with the same priority as .claude/CLAUDE.md itself, so .claude/rules/testing.md with no frontmatter is tier 1 wearing a different folder, not tier 2. The mechanism doesn't decide the tier. The loading behavior does.

What a scoped rule adds over the nested CLAUDE.md it replaces: the glob cuts across the directory tree instead of being pinned to one folder, so "every *.php file under app/Domains, but not the tests next door" is one line, instead of a rule you cannot express. Every rule file also lives in one folder instead of being scattered one per directory, so reviewing what conditional context exists in a project is a single ls, not a find across the tree. Same loading behavior as before, better shape:

---
paths:
  - "app/Domains/**/*.php"
---

# Domain layer rules

Tier 3: installed programs

A skill's name and description sit in a listing Claude can see from the start of the session, and that listing has its own budget: roughly 1% of the context window. When it overflows, Claude Code shortens descriptions starting with the skills you invoke least, so the ones you use constantly keep their full text and a skill you just added competes for space with everything else you've built. None of that costs much, which is the entire pitch: a project can carry thirty skills for a fraction of what thirty paragraphs in CLAUDE.md would cost, as long as most of them don't fire in most sessions.

The moment one does fire, that pitch stops applying. The full SKILL.md body enters context and stays resident for the rest of the session, at the same per-turn cost as anything in CLAUDE.md. Compaction treats it better than you'd expect but worse than the root file: the first 5,000 tokens of each invoked skill survive /compact, shared across a 25,000 token combined budget, filled starting from whichever skill fired most recently. Invoke enough skills in one long session and the ones you called early get dropped entirely, quietly, with no warning that they're gone.

Two things make a skill something other than either RAM or disk. It can bundle scripts that run without their code ever entering context, only the output does, which nothing in CLAUDE.md or docs/ can do. And you can turn off its automatic trigger with disable-model-invocation: true, so it only runs when you type /name, trading the "maybe it fires" problem for "you have to remember to ask." That flag does more than disable auto-firing: it pulls the name and description out of the listing entirely, not just out of the trigger, so a skill set this way is the one case that costs nothing at all until you invoke it. That second point cuts both ways: a skill can also grant itself tool access through allowed-tools, which makes a committed project skill something you review the way you'd review a settings file, not something you skim the way you'd skim a doc. Skills accept a paths: glob too, the same format as rules, but it only narrows when Claude considers firing one automatically, so a scoped skill is filtered, not guaranteed.

Skills are not disk, because disk is passive. A skill is an installed program with an entry in a lookup table, dormant until something calls it, and then it runs. That's also why the failure mode is specific. Putting a procedure behind a skill trigger is fine, because the cost of it not firing once is that Claude does the steps manually instead of running the script. Putting an invariant behind a skill trigger is not fine, because the cost of it not firing once is that the rule silently didn't apply, and a fuzzy description match is a bad place to gamble something that must always hold.

Tier 4: disk, unchanged

docs/ still works exactly the way the first post described it. DESIGN.md, PLAN.md, DECISIONS.md, long prose that humans read too, loaded only when something points to it and only because Claude decided to follow the pointer. It's still the weakest guarantee of the four tiers, and that's correct: disk was always supposed to be the tier you fall back to for material that doesn't need to be certain, only available.

One trap is worth closing here, since it's the most common way people think they're on disk when they aren't. @docs/DESIGN.md inside a CLAUDE.md is not a pointer, it's an import: the file is expanded and loaded into context at launch, same as everything else in the root file. A plain prose reference, docs/DESIGN.md, no @, is what actually stays on disk until Claude follows it. The first post used prose pointers throughout, which was the right call, more by luck than by design.

The four tiers side by side

Tier	Mechanism	Loaded when	Resident cost	Survives `/compact`
1. RAM	Root `CLAUDE.md`	Session start, in full	Every turn	Yes, re-read from disk and re-injected
2. Demand-paged RAM	`.claude/rules/*.md` with `paths:`	Claude reads a file matching the glob	Every turn after that, for the rest of the session	No, lost until Claude reads a matching file again (inferred, not documented)
3. Installed programs	Skill in `.claude/skills/`	Name and description always listed unless `disable-model-invocation`; body loads on trigger	Resident for the rest of the session once triggered	First 5,000 tokens per skill, 25,000 combined, most recent first
4. Disk	`docs/*.md` referenced by path (not `@` imported)	Only if Claude decides to read it	Every turn after Claude reads it	Whatever survives the summary

Read top to bottom and it's also a certainty gradient. Tier 1 is guaranteed. Tier 2 is guaranteed for the files it's scoped to. Tier 3 is probable, or certain only if you invoke it yourself. Tier 4 is optional. Deciding where a piece of instruction belongs is really deciding how much certainty it needs.

Applied to a Laravel and event sourcing project

The starter repo from the first post had three tiers: root CLAUDE.md, docs/, and a nested CLAUDE.md inside app/Domains. It now has all four:

claude-code-laravel-starter/
├── CLAUDE.md                    # tier 1: stack, commands, invariants
├── README.md
├── .claude/
│   ├── rules/
│   │   └── domain.md            # tier 2: paths: ["app/Domains/**/*.php"]
│   └── skills/
│       └── README.md            # tier 3: how to install a project skill
├── docs/
│   ├── DESIGN.md                # tier 4: domain model, aggregates, events
│   ├── PLAN.md                  # tier 4: phased, plan-first implementation
│   └── DECISIONS.md             # tier 4: lightweight ADR log
└── app/
    └── Domains/                  # rules replace the nested CLAUDE.md that used to live here

domain.md keeps the rule that used to live in the nested file: no framework imports in the domain layer, aggregates only record events, events are immutable and past tense. What changed is where it lives: one file in a folder you can review alongside every other conditional rule in the project, instead of a CLAUDE.md you have to remember exists three directories down. .claude/skills/ doesn't ship a fake example skill; it documents how to install the real one, my Laravel event sourcing skill, which designs and generates the aggregate, events, and projector for a new bounded context in conversation.

Four rules to take away

If Claude needs it every turn, it goes in CLAUDE.md. If it only matters inside files that match a pattern, it goes in a rule, not a nested CLAUDE.md. If it's a procedure with steps, a script, or a template, it goes in a skill, and anything that shouldn't fire on its own gets disable-model-invocation: true. If it's long enough that a human should read it too and Claude only needs it sometimes, it goes on disk.

The two-tier version of this held up fine for a while. It just couldn't tell you where to put the thing that runs.

There's no artisan schema:show, so I built one

Alberto Arena — Fri, 24 Jul 2026 06:32:36 +0000

You join a project. Forty tables, half of them undocumented, and a posts table that somehow relates to three other tables you've never heard of. Where do you start?

php artisan db gets you an interactive shell, and from there you're back to whatever dialect your database speaks: .schema on SQLite, DESCRIBE on MySQL, \d on Postgres. Laravel's own db:show and db:table commands are a step up, an overview of your tables or one table's columns, indexes, and foreign keys, printed straight to the terminal. But they're still one table at a time, in text. Nothing shows you the shape of the thing: which tables actually connect, and how, across the whole schema. So you end up either opening a DB client through an SSH tunnel, or drawing the diagram yourself on a whiteboard from memory, which is exactly as reliable as it sounds.

And that's the easy case, when you have shell access at all. On staging or production, where you actually need this the most because that's where the real schema drifted from the migrations, you often don't have a shell. Some organisations block SSH outright for compliance, which is exactly the situation I wrote about replacing with AWS Systems Manager for running Artisan commands. Even with a Run Command session in hand, that gets you a shell again, not a diagram.

So I built Truss.

What it does

Truss is a live database structure viewer for Laravel. It scans your actual schema, not your migration files, and renders it as a scrollable, zoomable ER diagram right inside your app.

Live ER diagram, rendered with Mermaid, of every table and how it connects.
Focus mode: click a table to isolate it and its foreign-key neighbours, centred and highlighted, so you're not staring at forty tables to understand one.
Filter by table name, and toggle native column types against Laravel-style labels.
Map-style pan and zoom, with auto-fit.
Structure only, always. Truss reads tables, columns, keys, and indexes. It never queries a single row, which is the whole point of being able to run it somewhere that matters.
Self-contained: Mermaid and fonts are vendored and served from the package, so it works offline and under a strict CSP. No CDN, nothing phoning home.
Cached and automatic: the snapshot rebuilds after migrations, so the diagram never goes stale.
Export the whole diagram as PNG or SVG, exactly as it's currently filtered and focused, so it drops straight into a design doc or a PR description instead of a screenshot. Per-table exports as JSON or CSV are also available from each table's menu.

Install it, visit /truss, and you get the diagram. No config, no separate service to run.

composer require albertoarena/laravel-truss

By default it's only enabled locally. To use it on staging or production you explicitly enable it and gate access behind a viewTruss authorization gate, so "safe to run in prod" doesn't mean "wide open in prod".

From the command line, too

db:show and db:table get you close, but they're still one table at a time, in text. php artisan truss:show prints that same cached, exclusion-filtered snapshot the diagram uses, as a table: one row per database table, with its column count and foreign-key count, the whole schema at once instead of one piece of it.

php artisan truss:show   # the whole schema as a table, in your terminal
php artisan truss:open   # or jump straight to the diagram

php artisan truss:open opens the dashboard in your default browser, honouring the route prefix and app URL. It prints the URL regardless, so it still works over a forwarded port on a headless host with no browser for it to open.

Both commands live under a truss: namespace rather than schema:. A package squatting Laravel's own schema: namespace is asking for a collision if the framework ever ships a schema:show of its own, which is the joke in this post's title.

Trying it without installing anything

If you want to poke at it before adding it to a project, there's a live demo running against a fictional schema, right in your browser. Pan, zoom, filter, focus a table, no install required.

How it's held up

I've dropped Truss into a few of my own Laravel projects since building it, including ones I hadn't touched in a while, and it's the fastest I've re-oriented myself in a schema I half-remembered. Clicking through foreign keys in focus mode beats reconstructing the relationships from migration file names, every time.

Get started

The documentation covers installation, the quick start, and authorization for non-local environments in more detail. It requires PHP 8.3+ and Laravel 12+.

Feedback welcome, as always.

Known dev.to gotcha from the plan notes: pasting long content into its textarea can silently drop a newline at a random spot and merge two lines (has happened to two code blocks before) — worth a scroll-through of both code fences before publishing.

Claude Code Routines: A Third Way Beyond /goal and /loop

Alberto Arena — Mon, 20 Jul 2026 06:24:20 +0000

A few months ago, Claude Code shipped /goal, a way to stop typing "keep going" every turn and let Claude work until a condition was actually met. That solved a real problem: staying in the loop with an open session so you didn't have to babysit it turn by turn. It didn't solve a different problem, the one where you want Claude to do something and you're not even at your laptop.

That gap just closed. Anthropic added routines: saved configurations that run on Anthropic's own cloud infrastructure, triggered by a schedule, an API call, or a GitHub event, with no open session and no machine required. It's currently in research preview, so behavior and limits may still shift, but the shape of the feature is clear enough to be worth understanding now.

What a routine actually is

A routine bundles three things: a prompt, one or more GitHub repositories, and a set of connectors (Slack, Linear, and other MCP integrations). Package it once, attach a trigger, and it runs on its own from then on, cloning the repository fresh each time and executing as a full, unattended Claude Code session.

There's no permission-mode picker and no approval prompts during a run. Whatever the environment and connectors allow, Claude can do without asking. That's the point (nobody's there to answer the prompt) but it also means the blast radius of a routine is defined entirely by what you scope it to, not by anything you can intervene on mid-run.

Creating one

The fastest way in is /schedule (alias /routines), run inside any CLI session:

/schedule daily PR review at 9am

/schedule in 2 weeks, open a cleanup PR that removes the feature flag

Claude asks follow-up questions about the repository, the prompt, and the cadence, then saves the routine to your claude.ai account. /schedule only sets up schedule triggers though: API and GitHub triggers need the web form at claude.ai/code/routines, where you can also review or edit anything the CLI created. /schedule list, /schedule update, and /schedule run manage existing routines from the terminal.

Three ways to trigger one

Scheduled. A recurring cadence (hourly, nightly, weekly) or a single run at a specific future time. The minimum interval is one hour, so this isn't a replacement for tight polling, it's for the kind of check that genuinely only needs to happen once a day or once a week.

API. Each routine gets its own endpoint and bearer token. POST to it and a new session starts, optionally carrying a text field with run-specific context, an alert body, a failing log line, whatever the caller wants to hand off. That text arrives wrapped in a block that labels it as untrusted data, so a routine's prompt has to explicitly opt in to acting on it. It's a deliberate guard: anyone holding a leaked token can send text, but they can't use it to redirect the routine into doing something the saved prompt never asked for.

GitHub events. Pull request and release events, with filters on author, title, branch, labels, draft state, and merge state. A routine can watch for pull_request.opened on a specific base branch and run your team's own review checklist before a human ever looks at the diff.

A single routine can combine more than one trigger. A PR-review routine might run nightly as a backstop, fire from a deploy script, and also react to every new pull request.

Routines vs /goal vs /loop

The three now cover genuinely different problems, not three flavors of the same one:

/loop re-runs a prompt on an interval, inside a session you have open, on your own machine. No completion check, just repetition. Good for polling a build or babysitting a PR while you're around.
/goal keeps a session working, on your machine, until a separate evaluator model confirms a condition holds. Good for a bounded task you kicked off and want finished properly before you look again.
Routines run on Anthropic's infrastructure, with no session and no machine required, triggered by time, an API call, or a GitHub event. Good for anything that should happen whether or not you're at your desk.

The practical filter: if the automation needs to survive you closing your laptop, it has to be a routine. Neither /loop nor /goal does, both stop the moment the session ends.

Where routines shine

Backlog maintenance. A schedule trigger set to 0 22 * * * (nightly at 10pm) reads issues opened since the last run, applies labels, assigns owners by code area, and posts a summary to a #triage Slack channel before the team's day starts.

Alert triage. A monitoring tool posts to the routine's API endpoint when an error threshold trips. The routine investigates the payload, correlates it with recent commits, and opens a draft PR with a proposed fix, so on-call reviews a diff instead of starting from a blank terminal.

Bespoke code review. A GitHub trigger fires on every pull_request.opened, applies your team's own checklist, and leaves inline comments for the mechanical stuff so human reviewers can focus on design.

Cross-repo porting. A GitHub trigger on merged PRs in one SDK repository ports the same change to a parallel SDK in another language, keeping two libraries in step without someone re-implementing each change by hand.

Where it gets tricky

Everything a routine does carries your identity. Commits and pull requests use your GitHub account. Slack messages and Linear tickets use your linked accounts. There's no separate "bot" identity to fall back on, so a routine with too many connectors attached can do a surprising amount in your name.

No approval gate means the environment is the only safety net. Network access, environment variables, and which connectors are included are configured once, up front, and apply to every run after that. Scope them to exactly what the routine needs, not to whatever happens to already be connected to your account.

Green doesn't mean the task succeeded. A green status means the session started and exited without an infrastructure error, nothing more. Whether Claude actually did what the prompt asked is a separate question you still have to check by reading the run.

Branch pushes are restricted by default. Claude can only push to claude/-prefixed branches unless you explicitly allow unrestricted pushes for a repository. It's a sensible default, but worth knowing before a routine's first PR shows up on an unexpected branch name.

This is a research preview. The API surface ships under a dated beta header, and Anthropic has already said behavior, limits, and field shapes may change. Don't build anything load-bearing on top of it just yet.

Runs share your regular usage quota, plus a separate daily cap. Routine runs draw down the same subscription usage as an interactive session, on top of an account-wide daily limit on how many routine runs can start. Set up several nightly routines and it's easy to assume each gets its own budget. It doesn't, so check your remaining runs at claude.ai/code/routines before you find out the hard way.

Practical advice

Start with a schedule trigger before reaching for API or GitHub triggers. It's the easiest to reason about and the easiest to pause if something looks wrong.

Strip the connector list down to what the routine actually touches. Every connector you leave attached is something Claude can use without asking, on every run, indefinitely.

Treat routine output the same way you'd treat a CI pipeline: review the diff, don't trust the status light. A run that "completed successfully" and a run that "did the right thing" are not the same claim.

If a routine acts on external input (an alert body, a webhook payload), write the prompt to reference that payload explicitly. Otherwise it just sits there as inert context and the routine won't act on it at all, which is the safe failure mode, but worth knowing in advance rather than discovering it during an incident.

Closing thought

/goal solved the problem of staying in a session without re-prompting it. Routines solve the problem of not needing a session at all. Pick the one that matches the problem you actually have, and for the first time, none of them requires bending one tool to do a different job.

Sources

Automate work with routines: official Anthropic documentation for routines, covering creation, triggers, connectors, and limits.
Run prompts on a schedule: official documentation for /loop and session-scoped scheduled tasks, including the comparison against routines and Desktop scheduled tasks.
Keep Claude working toward a goal: official documentation for the /goal command.
Claude Code /goal vs /loop: Stop Typing, Keep Going: the earlier post this one builds on.

10,000 downloads

Alberto Arena — Sun, 19 Jul 2026 14:18:33 +0000

I built it to solve a specific friction point: setting up a Spatie event-sourcing domain meant writing a lot of the same files every time — aggregates, events, projectors, reactors, read models. The generator takes a migration or a quick description of your model and scaffolds all of it in one artisan command. It's not a framework addition, just a time-saver.

composer require --dev albertoarena/laravel-event-sourcing-generator
php artisan event-sourcing:generate Post

10k is more than I expected when I published it. The package has a narrow focus and a niche audience — Laravel developers who've already bought into event sourcing — so seeing it spread this far is genuinely surprising.

The project didn't stop at the generator. Earlier this year I built a Claude Code skill (write-up) that adds a design conversation before the code generation, so you work through the domain boundaries before anything gets written. More recently, the filament-event-sourcing plugin (write-up) closes the gap between Filament's admin panel and your aggregates. The generator is still the foundation, but these fill in the parts it was never meant to handle.

Thanks to everyone who's used it, filed issues, or left feedback. The package is still actively maintained and the best place for questions is the GitHub issues.

Create a domain using Spatie event sourcing

Alberto Arena — Sun, 19 Jul 2026 06:57:04 +0000

Event sourcing is a powerful pattern for tracking changes to application state, offering a robust way to manage domain-driven design in Laravel. However, setting up an event-sourcing domain can be time-consuming and repetitive, especially when following best practices.

To streamline this process, I've created a Laravel package that automates the creation of event-sourcing domains using Spatie's event sourcing library. With just one artisan command, you can generate all the boilerplate code needed for your domain, including aggregates, events, and projectors.

This package empowers developers to focus on their business logic rather than spending time on repetitive setup tasks. Whether you're building financial systems, audit trails, or complex applications that require detailed state tracking, this package can help you get started faster and with less hassle.

Here's a sneak peek at how simple it is to use:

php artisan make:event-sourcing-domain MODEL --domain=DOMAIN

In this blog post, I'll walk you through how to use this package, explain its key features, and provide practical examples to help you integrate event sourcing into your Laravel projects efficiently.

👉 Check out the package on GitHub!

Understanding the command

The primary command provided by this package is:

php artisan make:event-sourcing-domain MODEL --domain=DOMAIN

This command generates the necessary structure and files for a complete event-sourcing domain in your Laravel project. Let's break it down:

Parameters

MODEL:

This represents the core entity or aggregate root for your domain.
Example: If you're building an e-commerce application, a MODEL could be Order, Product, or Customer.

--domain=DOMAIN:

This defines the domain or bounded context where your model operates.
Example: For an Order model, you might place it in a domain like Sales or Inventory.

Command Usage

Here's an example of how to use this command:

php artisan make:event-sourcing-domain Order --domain=Sales

Running this will generate the following structure:

app/
└── Domain/
    └── Sales/
        ├── Actions/
        │   ├── CreateOrder.php
        │   ├── DeleteOrder.php
        │   └── UpdateOrder.php
        ├── Aggregates/
        │   └── OrderAggregate.php
        ├── Events/
        │   ├── OrderCreated.php
        │   ├── OrderDeleted.php
        │   └── OrderUpdated.php
        ├── Projections/
        │   └── Order.php
        └──Projectors/
           └── OrderProjector.php

Example workflow

To demonstrate the power of this package, let's walk through an example of setting up a domain for managing Orders within a Sales domain in your Laravel application.

We'll assume that a migration already exists.

// database/migrations/2024_12_20_121314_create_orders_table.php
return new class extends Migration
{
    **
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('orders', function (Blueprint $table) {
            $table->uuid()->primary();
            $table->string('customer_email')->index();
            $table->string('customer_name');
            $table->string('status')->default('pending');
            $table->decimal('total_amount', 10, 2);
            $table->json('items');
            $table->timestamps();
        });
    }

    // etc.
};

Step 1: Generate the Event-Sourcing Domain

Run the make:event-sourcing-domain command:

php artisan make:event-sourcing-domain Order \
  --domain=Sales \
  --aggregate=1

Running this will generate the following structure:

app/
└── Domain/
    └── Sales/
        ├── Aggregates/
        │   └── OrderAggregate.php
        ├── DataTrasnferObjects/
        │   └── OrderData.php
        ├── Events/
        │   ├── OrderCreated.php
        │   ├── OrderUpdated.php
        │   └── OrderDeleted.php
        ├── Projections/
        │   └── Order.php
        └── Projectors/
            └── OrderProjector.php

Step 2: Use it

use App\Domain\Sales\Actions\CreateOrder;
use App\Domain\Sales\DataTransferObjects\OrderData;
use App\Domain\Sales\Projections\Order;

# This will create a record in 'orders' table, using projector OrderProjector
(new CreateOrder)(new OrderData(
  customer_email: 'john@acme.org', 
  customer_name: 'John Doe',
  total_amount: 110.2,
  items: [
    [
      'id' => 12345, 'name' => 'Whiskey bottle', 'quantity' => 2, 'price' => 55.1,
    ]
  ],
));

# Retrieve record
$order = Order::query()->where('email', 'john@acme.org')->first();

Advanced Examples

Generate PHPUnit tests

Read full documentation here

Another interesting feature is the ability to generate automatically PHPUnit tests for the model.

Run the make:event-sourcing-domain command:

php artisan make:event-sourcing-domain Order \
  --domain=Sales --unit-test

Generate notifications

Read full documentation here

The package allows to generate notifications (mail, Slack and Teams) with an option.

Run the make:event-sourcing-domain command:

php artisan make:event-sourcing-domain Order \
  --domain=Sales \
  --aggregate=1 \
  --notifications=mail,slack

Running this will generate the following structure:

app/
└── Domain/
    └── Sales/
        ├── Aggregates/
        │   └── OrderAggregate.php
        ├── DataTrasnferObjects/
        │   └── OrderData.php
        ├── Events/
        │   ├── OrderCreated.php
        │   ├── OrderUpdated.php
        │   └── OrderDeleted.php
        ├── Notifications/
        │   ├── Concerns/
        │   │   └── HasDataAsArray
        │   ├── OrderCreated.php
        │   ├── OrderUpdated.php
        │   └── OrderDeleted.php
        ├── Projections/
        │   └── Order.php
        └── Projectors/
            └── OrderProjector.php

What's next

Some Bluepoint column types are not yet supported. You can find the list at this link.

~~Update migrations cannot yet be used, but only create migrations.~~

👉 Hey, this is available now! (*)

~~Finally, the package will need to be properly tested with PHP 8.3 and released for that version.~~

👉 I did it! (*)

Conclusion

Event sourcing is a transformative approach to building applications with robust state management and a clear audit trail. By leveraging the Spatie event-sourcing library, combined with this Laravel package, you can drastically reduce the time spent setting up event-sourcing domains while ensuring consistency and best practices.

With a single artisan command, you can generate all the necessary files and structure for your domain, empowering you to focus on building the unique aspects of your application.

If you're ready to streamline your development workflow and dive into event sourcing, try the package today:

👉 Check out the package on GitHub!

Feel free to star the repository, report issues, or contribute to its development. Your feedback and contributions are invaluable for improving the package and making it even more powerful for Laravel developers worldwide.

Notes

On December 31, 2024, I have added support to PHP 8.3.

On February 16, 2025, I have added support for update migrations. 👉 Read documentation here.

On June 30, 2026, this package crossed 10,000 downloads on Packagist — read the retrospective.

Claude Code /goal vs /loop: Stop Typing, Keep Going

Alberto Arena — Sun, 19 Jul 2026 05:48:21 +0000

If you've spent any real time with Claude Code, you've been through this loop. You give it a meaningful task, something like refactoring a service layer or wiring up a new set of endpoints. It works for one turn, produces solid output, and then hands control back to you. So you type "keep going." It does another round. Stops again. You re-prompt. Another round. Another stop. An hour later you've typed "keep going" more times than you've typed actual code, and the irony of manually babysitting your autonomous coding agent starts to sting.

Anthropic shipped a fix for that, and it's five letters long.

What /goal does

The /goal command sets a completion condition for your session. After each turn, a small and fast evaluator model (Haiku by default) checks whether the condition has been met. If not, Claude starts another turn. If yes, the goal clears and you get a summary with time, turns, and tokens spent.

The syntax is dead simple:

/goal all tests in test/payments pass and lint is clean

That's it. Setting the goal counts as the first turn. You don't need to send a separate prompt.

The key design decision is separation. There are two models involved: one does the coding, and a different one decides whether the coding is finished. The evaluator reads the conversation transcript and makes a binary call: done or not done. If not done, it also returns a short reason that becomes guidance for the next turn. So if Claude thinks it's finished but three tests are still failing, the evaluator catches the gap and sends Claude back to work.

OpenAI shipped the same concept in Codex CLI around the same time, under the same name. Both implementations trace back to the "Ralph loop" pattern that the agentic coding community had been hand-rolling with bash scripts for months. Now it's built in. No custom scripting, no wrapper, no cron.

Where it shines

The best use cases share a common trait: the end state is verifiable and Claude can prove it within the conversation.

Test-driven migrations. "Migrate all v1 API calls to v2 and make sure every test passes." Claude reads the code, changes call sites one by one, runs the suite after each batch, and keeps going until green. This is the sweet spot. The goal condition maps directly to a command exit code. The evaluator has something concrete to check.

Issue backlog cleanup. "Close every open TODO in the /legacy folder." Claude works through them systematically. Each one gets resolved, the evaluator counts what's left, and the loop continues until the queue is empty.

File restructuring. "Split this 3,000-line file into focused modules, each under 300 lines, with all imports still resolving." Measurable, bounded, verifiable.

Design doc implementation. "Implement the acceptance criteria in SPEC.md and run the integration suite." If your spec is well-written, Claude has a checklist to work through and a way to prove completion.

In all these cases you're basically saying: here's the finish line, don't come back until you've crossed it. And it works surprisingly well when the finish line is clear.

Where it gets tricky

The evaluator only reads the conversation transcript. It doesn't run commands, browse the filesystem, or verify anything independently. This means the quality of the loop is entirely dependent on how well your condition can be proven through Claude's own output.

Vague goals fail quietly. "Improve the authentication system" gives Claude no way to know when to stop. It might keep refactoring forever, or it might stop after one change and declare victory. Both outcomes are plausible and neither is useful.

Long sessions drift. Claude manages a finite context window. During extended runs it compresses earlier turns into summaries. If your task spans dozens of turns, nuances from the beginning may be lost by the end. A 14-hour session sounds impressive in a blog post, but in practice the quality of the last hour may not match the first. Anthropic recommends including a turn or time limit directly in the condition ("or stop after 20 turns") to bound the loop.

Token costs add up fast. Every turn costs main-model tokens plus a small Haiku evaluation. One developer noted that the token use can scale dramatically compared to a supervised session. If you're on a metered plan, a runaway goal can burn through your budget before you finish your coffee.

Scope creep is real. Claude might notice a related bug while working on your goal and decide to fix it. That sounds helpful until it touches a file owned by another team or introduces a change you didn't ask for. Always include constraints in your condition: "do not modify files outside /src/payments" is not optional, it's a safety net.

It doesn't replace judgment. /goal is for execution, not for design decisions. If the task involves ambiguity ("should this be a queue or a synchronous call?"), Claude will pick an answer and keep going. You might not agree with the answer it picked, and by the time you check, there are fifteen files built on top of that assumption.

How to write a good condition

Anthropic's docs recommend structuring conditions around three elements: a measurable outcome, an explicit verification step, and boundaries around what should not be touched. That's good advice. In practice it means your condition should read like a checklist, not a wish.

A condition like this works:

/goal all tests in test/payments pass, lint exits 0, and no file outside src/payments is modified

A condition like this doesn't:

/goal make the code better

The condition can be up to 4,000 characters, so you have room. Use it to be specific. Include the exact commands that should be run, the directories that are in scope, and the files that are off limits.

/goal vs /loop vs regular prompting

Claude Code now has three ways to keep a session alive without constant prompting.

Regular prompting is your default. You send a message, Claude responds, control returns to you. Best for exploratory work, design conversations, and anything where you want to review each step.

/loop re-runs a prompt on a time interval. It doesn't check a condition. Useful for monitoring or repeated checks ("run the test suite every 10 minutes and report failures"), less useful for convergent tasks.

/goal runs until a condition holds. The evaluator is what makes it different: completion is decided by a fresh model, not by the one doing the work. Combined with auto mode (which approves tool calls within a turn), you get fully unattended execution.

The simplest way to choose: if the trigger is time, use /loop. If the trigger is a verifiable outcome, use /goal. If you want to review each step before the next one happens, just keep prompting normally.

Practical advice

Always work on a branch. Before starting a /goal session, commit your current state. If Claude goes sideways, you can git diff to see what happened and git checkout to undo it. This isn't optional.

Start small. Your first /goal should not be a full codebase migration. Pick something contained: a single module, a single test file, a clearly bounded task. Watch how Claude executes it. Learn what works before you scale up.

Include a turn limit. "or stop after 15 turns" is cheap insurance against runaway loops. You can always set a new goal after reviewing progress.

Review the diff like any PR. Autonomous work is still code that ships. Don't treat /goal output as automatically correct. Read the changes, run the tests yourself, and apply the same review standards you would for any contributor.

Pair it with CLAUDE.md. If your project has conventions, patterns, or off-limits areas that aren't obvious from the code, document them in your CLAUDE.md. Claude reads it at the start of every session and will respect those constraints during a /goal loop.

Closing thought

/goal is the most significant workflow change in Claude Code since auto mode. It formalises something developers were already doing with duct-tape scripts and "keep going" prompts, and it does it with an evaluator layer that's genuinely clever.

But it's a power tool, not magic. The better your condition, the better the result. The vaguer your condition, the more creative Claude gets with the interpretation, and "creative" is not always what you want from an autonomous agent editing your production code.

Use it for execution when the thinking is done. Keep the thinking for yourself.

Sources

Keep Claude working toward a goal — Official Anthropic documentation for the /goal command.
Claude Code /goal: A Field Guide with Games — Jason Croucher's hands-on walkthrough with practical examples and real session logs.
Codex /goal: OpenAI's Built-in Ralph Loop — Deep dive into the Codex CLI implementation and the Ralph loop history.
Claude Code /goal: Set a Finish Line, Walk Away — FindSkill.ai's breakdown of the feature with cost and token considerations.