Instruckt Laravel Laravel Package

Technical Evaluation

Architecture fit. Instruckt is a dev-only package that composes cleanly onto a conventional Laravel app: a service provider that registers routes only when config('instruckt.enabled') is true, a publishable config, optional publishable migrations, an optional laravel/mcp dependency, and a frontend delivered either as a Vite plugin or a Blade component. It sits entirely off the production request path — the Vite plugin is gated with apply: 'serve' (zero bytes in vite build), the Blade component is wrapped in @if(config('instruckt.enabled')), and the config default only turns on when APP_ENV=local. That three-layer gate is the correct pattern for developer tooling and is the single strongest architectural signal here.

Integration feasibility. The install path is one Composer command plus php artisan instruckt:install, which performs source codemods: injecting instruckt/vite into vite.config.*, adding import 'virtual:instruckt' to the JS entry point, and writing MCP server entries into .mcp.json, .cursor/mcp.json, and other agent configs. That is high leverage and also the primary feasibility risk — it mutates files that teams lint, format, and review. The compensating control is instruckt:uninstall, which enumerates and reverses every artifact with confirmation and --force / --keep-config / --keep-npm flags. That is a maturity signal most 0.4.x packages lack, and it materially lowers the cost of a failed pilot.

Technical risk.

• Build-vs-serve divergence. import 'virtual:instruckt' lives in app.js, but the plugin declares apply: 'serve'. Unless the plugin also resolves the virtual module to an empty stub during vite build, CI builds break. This must be verified on a throwaway branch before any rollout — it is the highest-severity unknown.
• Installer idempotency and format drift. Regex/AST edits to vite.config.js across TypeScript configs, custom plugin arrays, and Prettier-formatted files are a recurring source of noise. Expect manual cleanup in non-standard setups.
• Unauthenticated routes by default. middleware defaults to api, which carries no auth. Any environment where INSTRUCKT_ENABLED=true is set (shared staging, LAN-exposed *.test host, a misconfigured preview) exposes annotation CRUD. The instruckt prefix is discoverable.
• Two independently versioned halves. The Composer package and the instruckt npm package ship separately; the PHP config governs backend behavior while toolbar visuals live in vite.config.js. Version skew between the two is unmanaged by design.
• Annotation payload sensitivity. Screenshots and element/text context are captured from whatever the developer is looking at and written to storage/app/_instruckt/. There is no documented retention, redaction, or size cap.

Key questions. Who reviews the installer's diff in the merge? Does the Vite plugin stub the virtual module in build mode? Can api_middleware be set to include auth without breaking the toolbar? What is the retention policy for annotations.json and screenshots/, and is there a size ceiling on captures? Is the npm package pinned to a compatible range by the Composer package, or is that on us? Does the package behave correctly under Octane and in a container where storage/ is ephemeral?

Integration Approach

Stack fit. Laravel 11 or 12 (13 support landed in v0.4.26), PHP 8.2+, Vite, optional laravel/mcp. Best fit is a single-repo Laravel monolith with a standard vite.config.js and a Livewire or Blade frontend — the Blade view tracking middleware and SourceResolver (Livewire class → file:line via reflection, Blade view name → path) exist specifically to give the agent precise source anchors, and they degrade gracefully on plain Blade pages.

Migration path. Two lanes, and the second is the safer default for the first cohort:

1. Blade component only — drop <x-instruckt-toolbar /> into the layout. No codemods, no JS entry changes, reversible by deleting one line. Ideal for a pilot.
2. Vite plugin — the installer's preferred path, needed for server: false behavior and cleaner adapter wiring, at the cost of files under review.

For hosted or multi-instance environments (shared preview, ephemeral containers), the v0.4.27 additions are the migration path: INSTRUCKT_STORE=database with published migrations, INSTRUCKT_SCREENSHOT_DISK=s3 with signed URLs, and INSTRUCKT_MCP_TOKEN on the SSE endpoint.

Compatibility. The dependency surface is deliberately narrow and the v0.4.30 release unpinned laravel/mcp to ^1.0 so Instruckt can coexist with Laravel MCP 1.0 and laravel/ai 1.x. Flag that Laravel 13 support is ahead of most of the ecosystem — being early here is a compatibility bet, not a stability claim.

Sequencing.

1. Spike on a scratch branch: install, run vite build, confirm no virtual-module failure. Gate everything on this.
2. Pilot with 1–3 developers using the Blade component; measure whether annotations actually reduce round-trips versus plain screenshots-and-text.
3. If it sticks, move to the Vite plugin and commit the codemod diff with a note in the PR.
4. Enable MCP per agent (Claude Code, Cursor, Codex, Copilot) and install the instruckt skill directory so agents recognize pasted markdown and call get_all_pending / resolve without prompting.
5. Only then consider the database store and remote screenshot disk — those are hosted-preview concerns, not local-dev ones.

Operational Impact

Maintenance. No production runtime, so no uptime obligation — the maintenance surface is developer machines and repo config. The recurring cost is keeping the Composer package, npm package, and per-agent MCP configs in sync as developers onboard, upgrade Laravel, or switch editors. Version numbering is 0.4.x with frequent small releases (0.4.18 through 0.4.30 in the sample) and each one can bump agent config formats. Pin the Composer version and treat upgrades as a reviewed change, not a float.

Support. 176 stars, zero dependents, single maintainer. That is a real signal: no downstream ecosystem has validated the package, and there is no second contributor to absorb maintainer absence. It is also a dev-only dependency with a one-command uninstall, which caps the downside — a broken package costs an hour of cleanup, not an incident. Budget for the possibility of vendoring or forking if the project stalls, and prefer the Blade path precisely because it is the most forkable.

Scaling. Local per-engineer usage scales trivially — annotations.json in storage/app/_instruckt/ is per-machine, so there is no contention and no sharing (which is correct for the use case, but will surprise anyone who expects a teammate to see their annotations). Multi-user and multi-instance scenarios require the database store; the flat-file path has no documented locking and should not be used on shared infrastructure. Screenshots accumulate without a documented retention job — a cleanup command or a cron is our responsibility, not the package's.

Failure modes to watch.

• vite build failure from the unresolved virtual module (highest severity, blocks CI).
• Installer leaving a malformed vite.config.js or a duplicate MCP entry; uninstall mitigates but is itself a mutation.
• Enabled outside local — unauthenticated annotation endpoints and screenshots exposed on a reachable host.
• Clipboard auto-copy silently skipped on http://*.test because navigator.clipboard requires a secure context; users must use the toolbar copy button.
• MCP tool errors — get_screenshot now returns isError: true correctly (v0.4.27), which is important because a soft failure causes agents to hunt for the image by other means.
• Stale annotations surviving branch switches and reappearing on unrelated pages.

Ramp-up. Low for developers (one command, four keyboard shortcuts: A, F, C, X). The real ramp-up is for agents: they must be taught the paste-recognition pattern and the get_all_pending → fix → resolve loop, which is what the shipped SKILL.md is for. Plan on distributing that skill to every onboarded agent config, and budget one session per team to establish the workflow — the payoff only appears once both the human and the agent follow the loop.