Antigravity Laravel Kit Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require edneymatias/antigravity-laravel-kit --dev
   php artisan antigravity:install
   

   This creates a .agent folder in your project root with pre-configured AI agent templates.

2. First Use Case: Run a basic agent command to generate a Laravel-specific component:

   php artisan antigravity:run backend-specialist --task="Generate a controller for User resource with CRUD operations"
   

   The agent will output a scaffolded controller with Eloquent methods, validation, and API responses.

3. Where to Look First:

   • Agent List: Check the README table for available agents (e.g., backend-specialist, test-engineer).
   • Agent Directory: Explore .agent/ for YAML/JSON templates (e.g., .agent/backend-specialist/template.yml).
   • Artisan Commands: Run php artisan to see all antigravity: commands.

Implementation Patterns

Core Workflows

1. Task-Driven Development: Use agents to automate repetitive tasks:

   # Generate a Livewire component
   php artisan antigravity:run frontend-specialist --task="Create a Livewire form for User profile with validation"
   
   # Write Pest tests for a feature
   php artisan antigravity:run test-engineer --task="Generate Pest tests for UserController@store"
   

2. Integration with Laravel Ecosystem:

   • Livewire: Pair frontend-specialist with Livewire components for real-time UI logic.

     php artisan antigravity:run frontend-specialist --task="Add Livewire interactivity to a Blade form"
     

   • Eloquent: Use database-architect to generate migrations, factories, and seeders.

     php artisan antigravity:run database-architect --task="Create migration and factory for a Post model with soft deletes"
     

   • APIs: Leverage backend-specialist for API resource scaffolding with Sanctum/Passport auth.

     php artisan antigravity:run backend-specialist --task="Build API endpoints for a V1 User resource with rate limiting"
     

3. Workflow Automation: Chain agents for end-to-end feature development:

   # Step 1: Generate model + migration
   php artisan antigravity:run database-architect --task="Create Product model with relationships"
   
   # Step 2: Scaffold controller
   php artisan antigravity:run backend-specialist --task="Generate ProductController with API routes"
   
   # Step 3: Add tests
   php artisan antigravity:run test-engineer --task="Write Pest tests for ProductController"
   

4. Custom Templates: Extend existing agents by modifying .agent/[agent-name]/template.yml or adding new templates to the directory. Example:

   # .agent/custom-agent/template.yml
   name: "custom-agent"
   description: "Handles Laravel Forge deployments"
   template: |
     php artisan forge:redeploy --server={{ server_name }} --branch={{ branch }}
   

Integration Tips

• AI Service Providers: Configure your preferred AI provider (e.g., OpenAI, Anthropic) in .env:

  ANTIGRAVITY_AI_PROVIDER=openai
  ANTIGRAVITY_API_KEY=your_api_key_here
  

• Debugging Output: Use --verbose flag for detailed agent execution logs:

  php artisan antigravity:run backend-specialist --task="..." --verbose
  

• Environment Awareness: Agents respect Laravel’s .env (e.g., APP_ENV, DB_CONNECTION) for context-aware outputs.

Gotchas and Tips

Pitfalls

1. Template Overrides:

   • Issue: Custom templates in .agent/ may conflict with package updates.
   • Fix: Use --force during updates to preserve your changes:

     php artisan antigravity:install --force
     

   • Tip: Store custom templates in a separate directory (e.g., .agent/custom/) and reference them via --template flag:

     php artisan antigravity:run custom-agent --template=custom/
     

2. AI Rate Limits:

   • Issue: Free-tier AI providers may throttle requests during bulk operations.
   • Fix: Implement retries with exponential backoff in your agent’s execute() method (extend the base agent class).

3. Context Loss:

   • Issue: Agents may not retain state across multiple commands.
   • Fix: Use --context to pass previous outputs:

     php artisan antigravity:run backend-specialist --task="Generate User model" --context="previous_output"
     

4. Livewire/Blade Conflicts:

   • Issue: Auto-generated Livewire components may clash with existing Blade views.
   • Fix: Manually merge outputs or use --dry-run to preview changes:

     php artisan antigravity:run frontend-specialist --task="..." --dry-run
     

Debugging

1. Log Inspection:

   • Check storage/logs/antigravity.log for agent execution details.
   • Enable debug mode in .env:

     ANTIGRAVITY_DEBUG=true
     

2. Template Validation:

   • Validate YAML templates with:

     php artisan antigravity:validate-templates
     

3. Agent Isolation:

   • Test agents in a fresh Laravel installation to rule out environment conflicts.

Extension Points

1. Custom Agents:

   • Create a new agent by:
     1. Adding a YAML template to .agent/[agent-name]/.
     2. Publishing the agent class:

        php artisan vendor:publish --tag=antigravity-agents
        

     3. Extending Antigravity\Kit\Agents\Agent to add custom logic.

2. Hooks:

   • Override agent lifecycle methods (e.g., preExecute(), postExecute()) in your custom agent class.

3. AI Provider Swapping:

   • Implement a new AI provider by extending Antigravity\Kit\Services\AIService and binding it in config/antigravity.php.

Configuration Quirks

1. Caching:

   • Agent responses are cached by default (TTL: 1 hour). Disable in .env:

     ANTIGRAVITY_CACHE=false
     

2. File Permissions:

   • Ensure .agent/ is writable:

     chmod -R 755 .agent/
     

3. Livewire Version:

   • Agents assume Livewire 3.x. For older versions, specify in the task:

     php artisan antigravity:run frontend-specialist --task="Generate Livewire 2.x component"