Instruckt Laravel Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require joshcirre/instrukt-laravel --dev
   php artisan instruckt:install
   

   This handles config publishing, Vite integration, and MCP auto-configuration.

2. First Use Case:

   • Open a Blade view (e.g., resources/views/your-view.blade.php).
   • The package auto-injects a toolbar UI (if using adapters: ['blade'] in Vite config).
   • Click the toolbar to annotate elements (e.g., highlight a form field, add a comment).
   • Annotations are stored as structured JSON in storage/instrukt/annotations.json.

3. Viewing Annotations:

   • Access annotations via MCP (if enabled) or manually via:

     $annotations = \Instrukt\Instrukt::getAnnotations();
     

   • AI agents (e.g., GitHub Copilot) can read these via MCP tools.

Implementation Patterns

Workflow: Annotation-Driven Development

1. Browser Annotations:

   • Use the toolbar to annotate UI elements (e.g., "This button should redirect to /dashboard").
   • Annotations include:
     • selector: CSS selector of the element (e.g., #submit-button).
     • comment: Free-form text.
     • metadata: Custom key-value pairs (e.g., {"priority": "high"}).

2. AI Integration:

   • MCP Tools: Configure tools in config/instrukt.php:

     'mcp' => [
         'tools' => [
             'annotate' => [
                 'description' => 'Add or update UI annotations.',
                 'parameters' => [
                     'selector' => 'string',
                     'comment' => 'string',
                 ],
             ],
         ],
     ],
     

   • Call tools from your AI agent (e.g., Claude Code):

     {
       "tool": "annotate",
       "args": {
         "selector": "#login-form",
         "comment": "Add validation for email field."
       }
     }
     

3. Blade Integration:

   • Use the @instrukt directive to mark elements for annotation:

     <button @instrukt("submit-button")>Submit</button>
     

   • Or wrap elements:

     @instrukt('form-field')
         <input type="text" name="email">
     @endInstrukt
     

4. Livewire/Alpine:

   • For dynamic components, use the livewire adapter:

     instruckt({
       adapters: ['livewire', 'blade'],
     });
     

   • Annotations persist across Livewire interactions.

5. Export/Import:

   • Share annotations between environments:

     php artisan instrukt:export --path=annotations.json
     php artisan instrukt:import --path=annotations.json
     

Gotchas and Tips

Pitfalls

1. Vite Plugin Conflicts:

   • If using server: true in the Vite plugin, ensure your Laravel dev server isn’t running on the same port (default: 8000). Use:

     instruckt({ server: false }), // Recommended for Laravel.
     

   • Debug conflicts with:

     npm run dev -- --debug
     

2. Selector Leakage:

   • Annotations use CSS selectors, which may break if your UI changes. Test selectors with:

     \Instrukt\Instrukt::validateSelector('#dynamic-id');
     

3. MCP Tool Misconfiguration:

   • Tools must match the AI agent’s expected schema. Validate with:

     php artisan mcp:tools
     

   • Example error: Tool "annotate" not found → Check config/instrukt.php and restart MCP.

4. Storage Permissions:

   • Ensure storage/instrukt/ is writable:

     chmod -R 755 storage/instrukt
     

Debugging

1. Log Annotations:

   • Enable debug mode in config/instrukt.php:

     'debug' => env('INSTRUKT_DEBUG', false),
     

   • Check logs at storage/logs/instrukt.log.

2. Toolbar Not Showing:

   • Verify the Vite plugin is loaded and adapters include 'blade'.
   • Clear Vite cache:

     npm run dev
     

3. AI Agent Not Reading Annotations:

   • Confirm MCP is enabled ('mcp' => true in Vite config).
   • Test MCP tools with:

     php artisan mcp:test
     

Tips

1. Custom Metadata: Add structured metadata to annotations for AI context:

   // In browser console (after toolbar loads)
   instrukt.addAnnotation({
     selector: '#sidebar',
     comment: 'Collapse on mobile',
     metadata: { device: 'mobile', priority: 'high' }
   });
   

2. Conditional Annotations: Use Blade directives to toggle annotations in dev/staging:

   @if(config('app.env') === 'local')
       @instrukt('dev-only-element')
           <div>Debug info</div>
       @endInstrukt
   @endif
   

3. CI/CD Integration:

   • Export annotations before deploy:

     php artisan instrukt:export --path=annotations-prod.json
     

   • Import in staging to sync feedback:

     php artisan instrukt:import --path=annotations-prod.json
     

4. Performance:

   • Disable adapters you don’t use (e.g., adapters: ['blade'] only).
   • For large projects, lazy-load the toolbar:

     instruckt({ lazyLoad: true });
     

5. Extending Storage: Override the default JSON storage by binding a custom driver:

   // InstruktServiceProvider.php
   $this->app->bind(\Instrukt\Contracts\AnnotationStorage::class, function () {
       return new \App\Services\DatabaseAnnotationStorage();
   });
   

   Implement \Instrukt\Contracts\AnnotationStorage to use a database or cache.