Devtools Laravel Package

Technical Evaluation

What this is. jul6art/devtools is a Composer-installed developer/CI CLI that inspects a Laravel application and produces documentation artifacts — workflows, routes, commands, events, policies — plus an MCP surface and Claude "skills" for querying them. It is tooling that runs alongside an app, not a library the app calls at runtime.

Architecture fit. Good on paper. The Laravel adapter (ADR-0030) reads routes, commands and events through three Artisan calls and falls back to static reading when Artisan cannot answer. That is an out-of-band, read-only read of the application's own introspection surfaces — the lowest-coupling way to do this in Laravel. Blade is treated as Twig, i.e. parsed rather than rendered, which is the pragmatic choice but a heuristic. Because the package consumes Artisan output rather than framework internals, it should survive Laravel minor upgrades better than a package that hooks into the container or router. Confirm it is intended as a require-dev dependency and does not register a service provider, middleware or config that would ship to production.

Integration feasibility. Two adoption paths, both credible:

• Composer: composer update jul6art/devtools, then devtools claude:install for the second skill, then devtools init. Formats are described as additive, so existing generated docs survive regeneration.
• Pinned artifact: devtools.phar with a published SHA-256 and provenance attestation, plus ghcr.io/jul6art/devtools:3.4.0 built from that phar. This is the better story for CI: an immutable, verifiable tool version independent of composer.lock resolution and independent of your application's dependency graph.

The --switch-adapter command moves already-documented stacks onto the native adapter, which materially lowers the cost of upgrading an existing DevTools install rather than starting fresh.

Technical risk.

1. AI data egress. ai:run and devtools ask send content to the Claude API. Both are off by default, gated by <ai enabled="true"/> in .devtools/config.xml, with the key read only from ANTHROPIC_API_KEY. The defaults are correct, but enabling this transmits source-derived documentation to a third party and needs a security and, where applicable, legal sign-off. The non-AI path for devtools ask (--pages, the search_workflows MCP tool, the devtools-ask skill) is a genuine mitigation and should be the default internal posture.
2. Silent static fallback. "Static reading when Artisan cannot answer" is a resilience feature that can also produce plausible-but-incomplete documentation with no loud signal. We need to know how the tool reports degradation — exit code, warnings in output, a coverage count — before anyone trusts the output as an inventory.
3. Release surface vs. version number. Roughly ten ADRs land in a single 3.3 → 3.4 minor bump, including a new language runtime (Node), four new adapters, an AI subsystem, and a self-updating binary. Semver says minor; the blast radius says treat it as a major.
4. Supply chain. devtools self-update verifies SHA-256 and provenance before replacing anything — good design — but any self-updating binary is a surface to manage. Pin and never auto-update in CI.
5. Additional runtime dependency. The Node bridge (ADR-0031) and the Angular/Express adapters require a Node toolchain in the runner. PHP CI images may not have one, or may have an old one.
6. Newness. All of these adapters are brand new in this release. Expect first-month defect density to be higher than the core.

Key questions for the maintainer.

• Is this strictly require-dev? Does anything register in the production container?
• What exactly does workflows:check exit with, and which conditions fail the build (orphan calls only, or more)?
• How does the tool surface a static-analysis fallback, and can we make partial extraction a hard failure?
• Which PHP and Laravel versions are supported, and what is the stated support window?
• What is sent to the Anthropic API, is anything redacted or excluded by path, and are there size limits?
• Is there rate limiting or cost control on ai:run in CI?
• What does the MCP surface expose — read-only documentation queries, or anything that can execute?
• Who else maintains this, and what is the historical release and issue-response cadence?

Integration Approach

Stack fit. Designed for Laravel, so a Laravel monolith or a set of Laravel services is the natural home. The --link capability (ADR-0038) is the interesting one for us: matching a front-end's outbound calls against an API's routes, and reaching screens from an impact analysis, is a cross-service contract check that most teams do by hand or not at all. That is a different value proposition from "generate docs," and it is the part worth piloting.

Migration path. Upgrading is explicitly low-friction: composer update jul6art/devtools, devtools claude:install, and devtools init adding .devtools/search.idx to .gitignore. Every format is additive. Nothing here is a breaking change.

Compatibility cautions.

• .devtools/search.idx is a generated index and should never be committed. Confirm CI regenerates it and measure the cost — an index rebuild on every job may be the slowest step.
• workflows:rename (ADR-0036) rewrites a page, its history, and every reference. That is a repo-wide mutation. Run it on a branch, review the full diff, and never combine it with an adapter switch in the same commit.
• workflows:inspect --switch-adapter will produce a large one-time diff as documentation is rewritten in native-adapter form. Isolate it in a single reviewed commit so it can be bisected later.
• Cross-project linking requires multiple repositories checked out in one workspace, with credentials for each. That is an infrastructure change, not a config change.

Sequencing.

1. Week 1 — spike. Add as a require-dev dependency on one service, run devtools init on a scratch branch, read the generated output against known reality (count routes, commands, events against php artisan directly). Deliverable: a judgement on extraction accuracy.
2. Weeks 2–4 — report-only CI. Wire workflows:inspect and workflows:check into a non-blocking job. Log failures. Deliverable: false-positive rate for orphan-call detection.
3. Weeks 2–4 in parallel — pinning decision. Choose Composer pinning or the phar/image with SHA-256 verification. Do not adopt both; pick the one your CI can enforce, and disable self-update on runners.
4. Weeks 4–6 — cross-service pilot. One front-end plus its API with --link. Measure whether the orphan-call signal catches anything real before considering it a required check.
5. Later — AI, if ever. Only after a data-egress review and a funded key. Start with devtools ask --pages (no AI) and the search_workflows MCP tool, which deliver most of the discovery value with none of the exposure.

Operational Impact

Maintenance. The cadence is fast and ADR-heavy, which is a documentation positive and an operational caution: there is real design thinking here, but also a lot of new code arriving quickly. Pin the exact version. Avoid self-update outside developer laptops. Treat generated documentation as a build artifact where possible — regenerate rather than hand-edit, or the next adapter switch becomes a merge conflict.

Support. Effectively a single-maintainer package. That is the dominant operational risk, ahead of anything technical. The ADR trail, published provenance attestations, and the phar/image distribution all suggest a maintainer who takes release hygiene seriously, but bus factor remains one. Have a fallback plan: the outputs are static files, so the failure mode of losing the tool is degraded documentation, not a broken build — provided you never make workflows:check a required status without an owner.

Scaling. Local, CPU-bound CLI work; cost scales with repository size and the number of linked projects. Three concrete scaling constraints:

• The cross-project job needs every linked repository present. In a many-service estate that is a fan-in job, not a per-repo one.
• Node-based adapters mean the CI image carries both PHP and Node toolchains. Plan for a heavier runner image and a Node version pin.
• AI paths introduce network egress, latency, per-run cost, and an external availability dependency. Keep them off the critical path and out of required checks.

Failure modes to instrument.

• Artisan introspection fails, static fallback silently yields partial docs — false confidence in the inventory. Mitigate by comparing extraction counts against direct Artisan output in a periodic sanity job.
• workflows:check failing on orphan calls. Dynamic or constant-composed URLs are the likely false positives. Report-only until proven; then make it blocking deliberately, with a documented suppression mechanism.
• ANTHROPIC_API_KEY appearing in CI logs. Mask it, and verify that AI-enabled-but-keyless fails cleanly rather than writing half an artifact.
• .devtools/search.idx accidentally committed, producing merge conflicts and stale indexes. Enforce via .gitignore plus a CI check.
• Node process spawn failure on a minimal image, taking down the entire inspect rather than just the JS adapter. Ask whether adapters fail independently.
• workflows:rename leaving dangling references outside the repository — CI config, wikis, external links. The command cannot reach those; own the cleanup manually.

Ramp-up. Low for an individual contributor: devtools init plus claude:install, two skills, and a CLI whose subcommands are self-describing. Expect half a day for one engineer to produce and interpret output, and one to two weeks to reach a stable CI integration with one linked-project pair. The real ramp-up cost is organisational and sits in two places: (a) learning the tool's vocabulary — adapters, switching, linking, workflows versus pages — which is also the documentation's own vocabulary, so reading the output teaches it; and (b) the governance review required before any AI feature is enabled, which is a few days of security and legal time, not engineering time.

Recommendation. Adopt as a pinned developer and report-only CI tool for Laravel services; pilot cross-project linking where a front-end/API contract is currently undocumented; keep the AI features disabled until a data-egress review is complete, and prefer the non-AI devtools ask path when that review lands.