Instruckt Laravel Laravel Package

Product Decisions This Supports

• Build vs. buy for the human→agent feedback loop. This package is essentially a free prototype of a capability most teams are currently solving with screenshots-in-Slack and hand-written bug descriptions. Before committing engineering time to a bespoke internal tool, evaluate whether this closes enough of the gap.
• Inner-loop / DX investment sizing. If your team ships UI with AI coding agents (Claude Code, Cursor, Codex, Copilot), the bottleneck is increasingly specification quality, not code generation. This directly addresses that: element selector, component name, source file + line, classes, text content, and optional screenshot get packaged into structured markdown the agent can act on without a clarification round-trip.
• Roadmap input for the "design review → merged fix" cycle time. Adoption gives you a measurable before/after on time-to-fix for small UI defects and on the number of back-and-forth messages per UI change — concrete numbers to justify or kill further investment.
• MCP as a strategic interface bet. The package's agent surface (get_all_pending, get_screenshot, resolve) is a small, readable reference implementation of what "agent-readable application state" looks like. Useful as a pattern reference even if you never install it — particularly for teams deciding whether MCP tooling belongs in their own product architecture.
• Scoping a customer-facing version. If you ship an admin panel, site builder, or design tool, this demonstrates a UX pattern (click element → annotate → structured payload) you may want to productize. Note the delta: this package is explicitly dev-only and gated to APP_ENV=local; a customer-facing version is a different product with auth, multi-tenancy, and abuse concerns.
• Tooling standards and security review decisions. Adopting it forces an explicit decision on whether source-mutating installers (it edits vite.config.js, your JS entry point, and agent config files like .mcp.json) are acceptable in your repo — a governance question that will recur with every AI-tooling package you evaluate.

When to Consider This Package

Good fit when most of these are true:

• Laravel 11/12/13 stack (README states 11–12; v0.4.26 added Laravel 13 — verify against your version).
• Vite-based frontend build. The Vite plugin path is the primary, best-supported route and ships literally zero bytes to production (apply: 'serve'); the Blade component is the fallback.
• Blade and/or Livewire in the mix. The Livewire/Blade adapters and the server-side SourceResolver (component name → PHP class + line, view name → file path) are where this package earns its keep over a generic annotation tool. Framework-agnostic annotation is a commodity; framework-aware source resolution is not.
• Your team already works with an MCP-capable agent. Without an agent reading the annotations, the value collapses to "clipboard-formatted feedback."
• Small team, dev-only, local-first. Zero database migrations by default (flat JSON in storage/app/_instruckt/), fully reversible via php artisan instruckt:uninstall.

Look elsewhere or defer when:

• Non-Laravel stack, or a frontend with no Vite build and no Blade layout to hook into.
• You need production or stakeholder-facing feedback capture. This is hard-gated to local dev across three layers — that's a safety feature, not a limitation to work around.
• Repo hygiene forbids automated codemods to vite.config.js and JS entry points. This is the single biggest friction point; budget a PR review of the installer's diff.
• Security posture disallows adding MCP server entries to agent config files, or you can't yet govern which agent configs exist across the org.
• You need vendor assurance. Single maintainer, 176 stars, 0 dependents, and a release cadence that reads as one-person maintenance. No third-party production signal exists. Treat it as an experiment, not infrastructure.
• Multi-instance/hosted needs: v0.4.27 does add a database store, S3 screenshot disk with signed URLs, and Bearer-token auth on the MCP SSE endpoint — but the surrounding posture is still dev-tool, and you'd be leaning on the newest, least-exercised code paths.
• http://*.test local domains: clipboard auto-copy silently degrades (secure-context requirement). Workable via the toolbar copy button, but expect a confusing first-run experience.

How to Pitch It (Stakeholders)

For executives — one paragraph: This is a low-cost, fully reversible experiment in shortening the loop between "someone spots a UI problem" and "an AI agent fixes it." It's a dev-only Composer package: it installs with one command, is disabled outside APP_ENV=local at three independent layers, ships zero bytes to production, and uninstalls cleanly. The upside is measurable — fewer clarification round-trips per UI change and faster time-to-fix on small interface defects. The downside is bounded to a few hours of one engineer's time plus a code review of the installer's diff. Cost of trying it is near zero; cost of not trying it is continuing to pay the clarification tax on every UI iteration.

For engineering — the practical framing: Install as a --dev dependency, run php artisan instruckt:install, and review the diff before merging — it touches vite.config.*, your JS entry, and agent config files. Annotate a handful of real UI nits across a Livewire and a plain Blade page, hand them to your agent via MCP, and use instruckt.resolve so markers clear without a reload. Measure two things for two weeks: messages-per-UI-fix and wall-clock time-to-fix. If the numbers move, keep it; if not, instruckt:uninstall reverses everything including npm and agent configs.

Risks to state up front, not discover later:

1. Bus factor of one. 176 stars, zero dependents, no downstream production usage to point at. Pin the version; don't build process on it.
2. Source-mutating installer. Highest-risk surface. It edits files your team reviews and lints.
3. Dual dependency. Composer package plus an npm package — two supply chains, two upgrade paths, and version-skew is possible.
4. Dev-only by design. Don't let anyone scope it into a customer feedback feature without a separate product decision; the security and tenancy model would need to be built, not configured.
5. Config drift. v0.4.27 changed the config surface (api_middleware / mcp_middleware split, store, screenshot_disk, mcp_token). If you publish the config, re-publish or you'll silently run stale defaults.

Recommendation: Treat as a two-week, single-team spike with defined success metrics. Do not standardize across the org until you have your own before/after data — the star count is not evidence, your cycle-time numbers will be.