Devtools Laravel Package

Getting Started

Install as a dev dependency and let it scaffold its own workspace:

composer require --dev jul6art/devtools
vendor/bin/devtools init

init creates .devtools/, writes a starter .devtools/config.xml, and appends .devtools/search.idx to .gitignore — commit the config and the generated pages, never the index.

Your first useful run on an existing Laravel app is the inspect pass. In 3.4.0 the Laravel adapter (ADR-0030) reads routes, commands and events through Artisan rather than guessing from source, follows Blade the way it follows Twig, and treats policies as access decisions:

vendor/bin/devtools workflows:inspect

That produces workflow pages under .devtools/ describing what the app actually exposes. Read those before writing any yourself — the adapter output is the baseline the rest of the toolchain (check, impact, ask) reasons against.

Then install the Claude skills so your editor agent knows the same vocabulary:

vendor/bin/devtools claude:install

If the package registers a service provider in your app, the same commands are reachable as php artisan devtools …; the vendor/bin form works regardless and is the safer thing to put in scripts.

First real use case: point workflows:inspect at a legacy Laravel app and use the generated pages as onboarding documentation for both new hires and Claude Code sessions.

Implementation Patterns

CI gate on the docs themselves. Put workflows:check in your pipeline next to PHPUnit. It fails on broken references and, with linked projects, on orphan calls — so documentation drift becomes a red build rather than a stale wiki.

Link a front-end to its API. The strongest 3.4.0 addition for Laravel shops with a separate SPA or mobile client:

vendor/bin/devtools workflows:inspect ../web ../mobile --link
vendor/bin/devtools workflows:check          # fails on a call with no matching route
vendor/bin/devtools workflows:impact --linked --since=main

The front's HTTP calls are matched against your Laravel routes, and impact --linked walks forward to the screens that break. Run it on PRs that touch routes/api.php or a controller's public methods.

Deterministic answers before AI answers. devtools ask selects pages without any model call — via --pages, the search_workflows MCP tool, or the devtools-ask skill. Wire search_workflows into your MCP-enabled editor for local Q&A; only add --answer-style AI output once you've validated the page selection is sane, since a wrong page set produces a confidently wrong answer.

AI in CI, gated. ai:run writes the pending briefs through the Claude API. Leave it off locally; enable per-environment by setting <ai enabled="true"/> in .devtools/config.xml and supplying ANTHROPIC_API_KEY as a CI secret. A nightly job that refreshes briefs and opens a PR works well — the diff is reviewable documentation, not a black box.

Glossary as a style guide. Define domain terms once (Claude generates the definitions); every page then inherits the same language. This is the cheapest fix for the "three names for the same model" problem in a mature Laravel codebase.

Rename instead of hand-editing. workflows:rename moves the identifier, its page, its history and every reference. Prefer it over find-and-replace when a domain concept is renamed.

Static export for sharing. devtools export:site produces a disk-openable site — good for PR previews, architecture reviews, and handing docs to people without the repo.

Docker for constrained CI. ghcr.io/jul6art/devtools:3.4.0 saves you installing Node and the PHP toolchain in a docs-only job. Pin by digest.

Gotchas and Tips

AI is off until you say otherwise. <ai enabled="true"/> is required, and the key is read from ANTHROPIC_API_KEY only — there is no config-file key path. Don't try to smuggle it in via .devtools/config.xml; it won't be read and you'll leak a secret into a committed file.

.devtools/search.idx is gitignored by init. Fresh clones have no index, so devtools ask on a clean checkout will under-select pages until something rebuilds it. If your CI runs ask, rebuild the index first or gate that step to jobs that inspect beforehand.

The static fallback is a fallback. The Laravel adapter parses source statically when Artisan cannot answer — a broken boot, missing .env, or a failing service provider. In that mode routes registered dynamically from config or DB won't appear. If a route you know exists is missing from the pages, suspect the app failed to boot in the inspecting environment before suspecting the adapter.

Policies as access decisions means auth changes are doc changes. Editing a policy silently changes what the generated pages claim about authorization. Re-run inspect in the same PR.

Linked-project paths must resolve in CI. --link ../api ../mobile assumes a directory layout. In a monorepo or a GitHub Actions checkout, the sibling paths won't exist — check out both repos or run the linked check from a job that has them.

Formats are additive, but generated pages are still code. Nothing in 3.4.0 breaks v3.x output, so upgrading is composer update jul6art/devtools plus devtools claude:install for the second skill. Still review the regenerated diff: a new adapter reading more faithfully will change pages, and that's the interesting part of the upgrade.

Prefer the pinned version over self-update in automation. devtools self-update verifies the SHA-256 and provenance attestation before replacing anything, which is right for a workstation. In CI, pin the composer constraint or the image digest instead — reproducibility beats self-healing.

Node bridge uses your compiler. JS/TS is read with the project's own tsc in a single Node process, so version skew between your typescript and the bridge is the first thing to check when Angular/Express extraction looks wrong.