Ubi ignis, ibi crustum; ubi non ignis, ibi opus tardum.
AI coding assistants are impressive. They write controllers, invent migrations, and generate tests with confidence. Then you open the pull request and notice problems. The associations use the wrong strategy. The queue job does not match CakePHP Queue 2.x. The “helper” the agent invented already exists in your plugin. The model was not bad at coding. It was coding without real knowledge of your application.
That is the gap I wanted to close with Ignis (crustum/ignis). It is not another chatbot added on top of CakePHP. It gives agents the same things a good teammate already has: clear conventions for your stack, deeper knowledge when they work in a specific area, and live access to the running application.
Installing Ignis is one Composer command and a short bootstrap step. After that, bin/cake ignis install sets up guidelines, skills, and MCP config for Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot, Junie, and similar tools. You do not teach the agent CakePHP from zero in every session. You load the project rules once and let the tools use them.
The Problem Is Not Intelligence. It Is Context.
Generic models know “a PHP framework.” They do not know that your project runs CakePHP 5.4, that HasMany now defaults to subquery, that Tessera tokens need CheckTokenMiddleware, or that your Orders table already has findActive(). So they guess. Sometimes the guess is excellent. Often it costs you time.
I kept seeing the same kinds of mistakes. Agents used APIs from last year’s CakePHP book instead of the major version you actually installed. They created new abstractions instead of using Bake, fixtures, or existing table methods. They invented a database schema instead of reading yours. They ignored logs and routes and tried to debug with shell grep alone.
Ignis gives agents visibility into how this CakePHP app should be built, and into what the app looks like right now.
What Ignis Actually Ships
Ignis has three parts that work together.
AI guidelines are instruction files built from Twig templates and turned into plain text. They load at the start of a session. They cover PHP and CakePHP conventions, testing habits, MCP usage, and package-specific advice when those packages are installed. Versioned folders keep CakePHP 5 guidance separate from CakePHP 6 changes. PHP minor folders build up to the PHP version you run.
Agent skills are modules the agent loads only when needed. Guidelines stay broad so the agent is not overloaded. Skills become active when the work is specific, such as queue jobs, migrations, broadcasting, or scheduling. You get less noise in context and clearer advice when it matters.
An MCP server gives live application tools. Agents can inspect schema, run read-only queries, check routes and config, read logs and browser console output, build absolute URLs, read host time in App.defaultTimezone, and run PHP in the application context. The agent stops guessing the table shape. It asks.
Load PluginManifest, Mcp, and Ignis, run manifest install, then:
composer require crustum/ignis --dev
bin/cake plugin load Crustum/PluginManifest
bin/cake plugin load Crustum/Mcp
bin/cake plugin load Crustum/Ignis
bin/cake manifest install --plugin Crustum/Ignis --with-dependencies
bin/cake ignis installEnable the cake-ignis MCP server in your editor. After that, you are coding with an agent that can see your app, not only your open files.
Guidelines vs Skills: Why Both Exist
Think of guidelines as the orientation email every new hire gets on day one. Skills are the wiki page you open when you are actually building a Queue job.
Guidelines are always loaded. They give foundational conventions. Skills load when the domain matches, and they focus on how to implement a feature. Path-specific rules can live in optional @scoped blocks and become managed rules. Skills stay for orientation only.
Path-scoped guidelines deserve a short note. You can wrap rules in @scoped(['src/Controller/**']) … @endscoped. When you turn this option on, Ignis extracts those blocks into .ai/rules/ignis. Editors then load controller advice only while you work in controllers. Keep the path patterns narrow. Do not put the whole src/** tree into one scoped block.
Custom app guidelines live under .ai/guidelines/. Matching paths override Ignis defaults. Plugin authors can ship resources/ignis/guidelines/core.twig, so anyone with Ignis and your package installed gets your conventions without searching separate docs.
Skills That Follow Your Composer Lockfile
When you run ignis install, Ignis looks at what is actually installed. If you have crustum/broadcasting, you get broadcasting-development. If you use CakePHP Queue, the skill pack can offer queue-development for major version 2. CakeDC Users 16 gets guidance for that major, not a vague “auth” talk that tries to fit every version.
Skill packs (crustum/cakephp-skills) hold shared assets for many CakePHP and CakeDC targets:
resources/ignis/pack/{vendor}/{package}/
guidelines/…
skills/…
{major}/
guidelines/…
skills/…Ignis uses the shared base first, then the major folder that matches composer.lock. First-party CakePHP packages and allowlisted Crustum targets compose automatically. Other vendors can be selected at install time. In a monorepo you can also add skills under .ai/skills/{name}/SKILL.twig and override names you do not want.
If you maintain a plugin, add this file:
resources/ignis/skills/your-package-development/SKILL.twigUse YAML frontmatter with name and description, plus short Markdown that tells agents what to do. Write a clear description so agents know when to activate the skill. Put lasting path rules in guidelines with @scoped, not only inside the skill body.
The MCP Server: Eyes Into the Running App
Guidelines teach “how.” MCP tools answer “what is true here.”
Start the server with:
bin/cake ignis mcpOr register it manually:
{
"mcpServers": {
"cake-ignis": {
"command": "php",
"args": ["bin/cake.php", "ignis", "mcp"]
}
}
}I use several tools all the time. Database Schema shows columns, indexes, and foreign keys before I write migrations or Table classes. Database Query runs read-only SQL instead of one-off scripts. Application Info reports PHP, CakePHP, the database engine, and ecosystem package versions. Get Absolute URL builds the correct scheme, host, and port before I share a link. Current Time returns the host clock in App.defaultTimezone, which is safer than a random shell date. Last Error and Read Log Entries read real log channels. Browser Logs show console errors from the page the user is looking at. Tinker runs PHP in full application context. List Routes, Config Read, and List Commands help the agent learn the app structure without long file searches.
This is the difference between “I think the column is user_id” and “the schema says owner_id, it is indexed, and it is a foreign key to users.” Agents that use these tools write code for the database you have, not the database they imagined.
A Day With Ignis, Not a Demo Script
CakePHP plugins often hide the hard parts behind a small public API and a lot of internal detail. Broadcasting is a good example. You want the order updates to reach the browser in real time. Without Ignis, the agent may invent its own WebSocket layer, reinvent method names that do not exist here, or miss private channels and authorization. You spend the session correcting the integration instead of shipping the feature.
With Ignis, the story changes as soon as crustum/broadcasting is installed. Guidelines and the broadcasting-development skill feed the agent the real surface: a BroadcastableInterface event, broadcastChannel(), broadcastData(), the broadcast() helper, channel auth, and how Echo fits on the client. The agent does not need to rediscover the plugin from source on every request. It already knows the intended path, the same way a teammate who has used the package before would.
That pattern repeats across the ecosystem. Queue, Tessera, Notification, and other packages can ship the same kind of knowledge. The public API stays small. The internals stay in the plugin. Ignis makes sure the agent meets the package on its own terms from the first reply.
Browser Logs: The Frontend Half of the Story
When debug is on and the browser logs watcher is enabled, Ignis injects a small script that posts console output to POST /_ignis/browser-logs. The agent’s browser-logs tool reads that buffer.
Your host must skip CSRF for that path with BrowserWatcher::shouldSkipCsrf(). If Auth RBAC would block the request, you also need to allow unauthenticated access. That design is intentional for local debugging. Do not leave an open ingest endpoint unprotected in production.
Once this is set up, the loop is simple. The user clicks. Console errors arrive. The agent reads them and fixes the template. You do not need screenshots of the browser console.
Keeping Knowledge Fresh
Packages change. Major versions ship. Skills improve. Refresh local Ignis assets with:
bin/cake ignis updateHook it into Composer if you want it automatic:
{
"scripts": {
"post-update-cmd": [
"@php bin/cake.php ignis update"
]
}
}By default, update also notices newly installed packages and can offer their guidelines and skills. Use --no-discover when you only want to refresh what is already published.
If you work in a plugin folder as its own Cursor or Claude project, point install at that path while packages are still discovered from the host app:
bin/cake ignis install --path=plugins/mypluginGenerated MCP config and guideline files can be recreated. Many teams add them to .gitignore and treat ignis install and ignis update as the source of truth.
Closing Thoughts
AI-assisted CakePHP development fails when the agent is smart but blind. Ignis does not replace judgment, code review, or tests. It removes predictable mistakes: wrong major APIs, invented schema, ignored package conventions, and debugging without logs.
Guidelines teach the project style. Skills deepen the domain. MCP tools show the living application. Together they make “pair with an agent” feel closer to “pair with someone who already read the book, the plugin docs, and your schema.”
Install it on your next CakePHP 5 project. Run ignis install, turn on the MCP server, and ask for something that used to take half a day of corrections. I think you will feel the difference the first time the agent opens the schema before writing the migration.
Your agents do not need more confidence. They need Ignis.
