Devtools Laravel Package

Product Decisions This Supports

• Build vs. buy for architecture knowledge management. This is a credible buy/self-host candidate when the alternative is an internal "keep the docs updated" initiative: it replaces convention-and-discipline with a generated artifact set (ADRs, workflow pages, glossary) that lives in the repo. Evaluate it against Confluence/Notion + a docs-linting script, not against a full EA tool.
• Documentation-as-a-verified-artifact, not a wiki. workflows:check failing on orphan calls and the ADR/workflow page generation turn documentation into something CI can gate. That supports a roadmap decision to treat doc drift as a defect class with a quality threshold, rather than a best-effort chore.
• Cross-repo impact analysis for release planning. workflows:inspect ../api ../mobile --link matches a front end's HTTP calls against the API's routes, and workflows:impact --linked walks forward to affected screens. This is directly usable in "what breaks if we change this endpoint?" triage, sprint scoping, and API deprecation planning — a decision PMs usually make on intuition.
• Stack coverage commitments. The Laravel adapter (routes, commands, events, Blade, policies-as-access-decisions), plus Node, Angular and Express adapters, means the same documentation pipeline can cover a PHP backend and a JS/TS front end. That supports a decision to standardize documentation tooling across a polyglot repo instead of running per-stack tools. It also constrains future stack choices: adopting a runtime outside PHP/Symfony/Laravel/Node/Angular/Express means falling back to generic inspection.
• AI investment posture. All Claude-dependent features are opt-in and default-off (<ai enabled="true"/>, ANTHROPIC_API_KEY only). This lets you ship the deterministic value first and defer the "do we let an LLM read our source in CI?" decision to a separate, reversible call — useful for roadmap sequencing and for security review.
• Data residency / deployment model. A signed phar with SHA-256 and provenance attestation, a GHCR image, and export:site for offline static docs mean no SaaS dependency and no source leaving your perimeter unless you enable the AI paths. That supports a "self-hosted only" procurement stance.
• Onboarding cost reduction. A generated, navigable map of routes, commands, events, guards, and their links is the artifact new engineers actually need. Frame this as time-to-first-PR, not as documentation quality.
• Tooling consolidation. workflows:rename migrating a workflow's page, history and every reference, and workflows:inspect --switch-adapter migrating a stack to a native adapter, reduce the switching cost of reorganizing. Low-glamour, but it is what makes adoption survivable past the first quarter.

When to Consider This Package

Consider it when most of the following hold:

• Laravel/Symfony is a primary backend, and the team already accepts ADRs or wants to start.
• There is a JS/TS front end (Angular or Express natively; other Node stacks via the compiler-backed bridge) whose API calls you want traced against backend routes.
• Documentation decay is a named pain, typically a multi-repo or monorepo setup where the API contract and the client drift apart and nobody notices until QA.
• You can run a CLI in CI and are willing to make workflows:check a gate.
• Self-hosting is acceptable or preferred — you are comfortable pinning a phar/image version, verifying the attestation, and managing devtools self-update yourself.
• The AI features are a bonus, not the justification. Adopt on the deterministic introspection and diffing; treat the Claude-backed glossary, ai:run and devtools ask as a later, opt-in phase (and note that devtools ask has a non-AI path via --pages, the search_workflows MCP tool, and the devtools-ask skill).
• You want a small-surface pilot: one Laravel service plus one front end, with --link, before committing.

Look elsewhere when:

• Your stack is outside the native adapter set (Java, .NET, Go, Python, Ruby service backends). The value proposition is native introspection; generic fallbacks give you much less.
• You need an owned vendor relationship — SLAs, support contracts, roadmap influence. This reads as a single-maintainer project with ADR-documented design decisions; that is a legitimate quality signal but not a support commitment. Budget for the exit cost of a generated-artifact format you could keep even if the tool goes away (a real mitigation: the output is Markdown in your repo).
• AI/LLM usage in CI is prohibited outright. The deterministic core still works, but you forfeit the glossary generation, ai:run briefs and AI answers — verify the remaining surface meets your need before adopting.
• You need a hosted portal with RBAC, SSO, commenting and search analytics. export:site produces static docs from disk, not a collaborative knowledge platform.
• Nobody owns the CI gate. Without a named owner, workflows:check gets disabled within two sprints and the generated docs rot faster than hand-written ones because they look authoritative.

How to Pitch It (Stakeholders)

For executives (one paragraph): Engineering's architecture documentation drifts out of date because keeping it current is manual work nobody is measured on. This tool generates that documentation from the code itself — routes, commands, events, access rules, and the calls a front end makes into an API — and can fail the build when the docs and the code disagree. It runs entirely on our own infrastructure (signed binary or container image, no hosted service), it can produce an offline static site, and its AI features are off by default and require an explicit key. The business case is faster onboarding and fewer integration surprises during release planning; the cost is a small CI integration and a pilot on one service and one front end. Recommended as a time-boxed pilot, not an org-wide mandate.

For engineering leads: The pitch is that it reads your app the way your framework does — three Artisan calls for Laravel, static reading as fallback, Blade treated like Twig, policies surfaced as access decisions — so the output reflects routing and authorization reality rather than someone's memory. Formats are additive and composer update plus claude:install is the whole upgrade, so the integration cost is genuinely low. The linked-projects mode is the differentiator: it turns "which screens does this endpoint change touch?" into a command.

For security and platform review: Three points to clear. (1) The phar is SHA-256 hashed with a provenance attestation and self-update verifies both before replacing — confirm that satisfies your supply-chain policy, and pin the image digest rather than the tag. (2) AI paths are disabled unless .devtools/config.xml opts in, and the key is read only from ANTHROPIC_API_KEY; treat enabling it as a separate review covering what source text reaches the API. (3) .devtools/search.idx is added to .gitignore by init — decide intentionally whether generated indices belong in artifacts.

Risks to state plainly: single-maintainer concentration; a hard dependency on Anthropic for the AI-adjacent features; a documentation gate that only holds if a team owns it; and version lock-in is low (Markdown in-repo) but tool lock-in is real if you build process around the CLI's specific checks.