Laravel Copilot Agents

10 agents · 9 file-type instructions · 9 reusable prompts · GitHub Copilot support

The production-ready agentic setup for Laravel projects. Custom agents, file-type instructions, reusable prompts, and cross-tool context files — extracted from a real Laravel codebase with actual architecture rules, conventions, and tech debt tracking that the AI follows.

Not a generic config pack. Not starter templates. A complete system that makes AI understand your Laravel project's architecture and enforce your team's conventions.

---

The Guide

The setup guide explains the full 4-layer instruction system, with examples and patterns for each component.

Copilot Agentic Setup Guide	How this setup works — file hierarchy, glob patterns, agent design, prompt templates, cross-tool compatibility. Read this first.

---

Quick Start

Get up and running in under 2 minutes:

Step 1: Clone the repo

git clone https://github.com/nondito-soft/laravel-copilot-agents.git

Step 2: Copy to your Laravel project

# Copy Copilot agentic files
cp -r laravel-copilot-agents/.github your-laravel-project/

# Copy universal context files
cp laravel-copilot-agents/AGENTS.md your-laravel-project/

Step 3: Customize for your project

Edit the files to match your actual stack, architecture, and conventions. See What to Customize below.

Step 4: Start using

# Invoke an agent in Copilot chat
@scaffolder Add a Department module

# Or use a reusable prompt from the prompt picker
> new-module

That's it. You now have 9 agents, 9 instruction sets, and 6 prompts working with your codebase.

Alternative: Don't want to copy? Browse the files and create your own from scratch using the patterns shown here.

⚠️ Important: Customize for Your Project

These files encode your specific architecture and conventions. Before running agents, update:

• .github/copilot-instructions.md — stack, rules, directory map
• .github/instructions/*.instructions.md — your code patterns and examples
• .github/agents/*.agent.md — your team's workflows
• AGENTS.md — your complete architecture guide and known tech debt

See What to Customize for details.

---

How It Works

GitHub Copilot uses a 4-layer instruction system — each layer is loaded at a different time and serves a different purpose:

Layer	Files	When Loaded	Purpose
1. Global	.github/copilot-instructions.md	Every Copilot interaction	Stack, architecture rules, conventions
2. File-type	.github/instructions/*.instructions.md	When editing files matching the applyTo glob	Per-filetype patterns and constraints
3. Agents	.github/agents/*.agent.md	When you invoke @agent-name in chat	Specialized multi-step workflows
4. Prompts	.github/prompts/*.prompt.md	When you select from the prompt picker	One-click task templates

---

What's Inside

laravel-copilot-agents/
|
|-- .github/
|   |-- copilot-instructions.md               # Global rules (auto-loaded on every interaction)
|   |
|   |-- instructions/                          # File-type conventions (auto-applied by glob)
|   |   |-- laravel-controllers.instructions.md    # app/Http/**/*.php
|   |   |-- laravel-services.instructions.md       # app/Services/**/*.php
|   |   |-- laravel-models.instructions.md         # app/Models/**/*.php
|   |   |-- laravel-migrations.instructions.md     # database/migrations/**/*.php
|   |   |-- laravel-seeders.instructions.md        # database/seeders/**/*.php
|   |   |-- laravel-routes.instructions.md         # routes/**/*.php
|   |   |-- laravel-lang.instructions.md           # resources/lang/**
|   |   |-- laravel-tests.instructions.md          # tests/**/*.php
|   |   |-- vue-inertia.instructions.md            # resources/js/**
|   |
|   |-- agents/                                # Specialized agents (invoked via @agent-name)
|   |   |-- scaffolder.agent.md                    # Scaffold a complete new module
|   |   |-- documentor.agent.md                    # Sync docs with codebase
|   |   |-- code-reviewer.agent.md                 # Code standards audit
|   |   |-- tester.agent.md                        # Generate missing PHPUnit tests
|   |   |-- package-upgrader.agent.md              # Safely upgrade dependencies
|   |   |-- security-auditor.agent.md              # OWASP vulnerability scanning
|   |   |-- deployer.agent.md                      # Deployment checks and execution
|   |   |-- code-refactorer.agent.md               # Dead code and complexity reduction
|   |   |-- pr-reviewer.agent.md                   # Review changesets against conventions
|   |
|   |-- prompts/                               # One-click reusable task templates
|       |-- new-module.prompt.md                   # Scaffold a new resource
|       |-- generate-tests.prompt.md               # Run and generate missing tests
|       |-- review-changes.prompt.md               # Review staged changes
|       |-- sync-docs.prompt.md                    # Update docs to match code
|       |-- security-audit.prompt.md               # Run security audit
|       |-- upgrade-deps.prompt.md                 # Audit and upgrade packages
|
|-- AGENTS.md                                  # Root context file (all AI tools read this)
|-- docs/
    |-- copilot-agentic-setup-guide.md         # How this setup works (start here)

---

Which Agent Should I Use?

Not sure where to start? Use this quick reference:

I want to...	Agent	What it does
Add a new module/resource	@scaffolder	Generates the full stack: migration → model → service → FormRequests → controller → routes → permissions → translations → feature doc
Write or fix tests	@tester	Writes missing PHPUnit Feature and Unit tests with proper assertions
Review my code	@code-reviewer	Audits for standards, security, localization, and theme compliance
Review a PR/changeset	@pr-reviewer	Checks architecture, naming, permissions, translations, and tests
Update documentation	@documentor	Scans codebase and updates all docs to match reality
Find security issues	@security-auditor	OWASP-aligned vulnerability scanning across the full stack
Upgrade dependencies	@package-upgrader	Safely upgrades Composer and npm packages with compatibility checks
Clean up code	@code-refactorer	Dead code removal, duplication reduction, complexity analysis
Format code	@code-formatter	Runs Pint (PHP), Prettier (JavaScript/Vue), validates formatting consistency
Deploy the app	@deployer	Pre-deploy checks, deployment execution, post-deploy verification, rollback

Common Workflows

Adding a new feature:

@scaffolder Add a Department module with name, code, and parent_id
                    → generates migration, model, service, controller, routes, permissions, docs

@tester Generate tests for DepartmentController and DepartmentService
                    → writes Feature + Unit tests with full coverage

@code-reviewer Review the Department module
                    → audits against project conventions, flags issues

Preparing for production:

@security-auditor Run a full security audit
                    → OWASP Top 10 scan, exposed secrets, mass assignment, SQL injection

@tester Run all tests and generate missing ones
                    → ensures coverage before deploy

@deployer Run pre-deploy checks
                    → environment, migrations, config, dependencies

Maintaining the codebase:

@code-refactorer Find dead code and unused dependencies
                    → identifies removable code without breaking changes

@documentor Sync all docs with the current codebase
                    → updates AGENTS.md, feature docs, README

@package-upgrader Check for outdated packages
                    → version matrix, breaking changes, safe upgrade path

---

File-Type Instructions

When you edit a file, Copilot automatically loads the matching instruction set based on the file path. No manual invocation needed.

Instruction File	Applies To	What It Enforces
laravel-controllers.instructions.md	app/Http/**/*.php	HasMiddleware, route model binding, Inertia responses, thin controllers
laravel-services.instructions.md	app/Services/**/*.php	BaseModelService, DB transactions, activity logging, business logic
laravel-models.instructions.md	app/Models/**/*.php	$fillable, SoftDeletes, relationships, model constraints
laravel-migrations.instructions.md	database/migrations/**/*.php	Required columns, SoftDeletes, naming conventions
laravel-seeders.instructions.md	database/seeders/**/*.php	Permission seeder structure, required fields
laravel-routes.instructions.md	routes/**/*.php	Auth group structure, named routes, breadcrumbs
laravel-lang.instructions.md	resources/lang/**	Translation key conventions, file organization
laravel-tests.instructions.md	tests/**/*.php	RefreshDatabase, permission seeding, Inertia assertions
vue-inertia.instructions.md	resources/js/**	Inertia patterns, shared data, Tailwind CSS, component styling

---

Reusable Prompts

One-click task templates — select from the prompt picker in Copilot chat:

Prompt	What it does
new-module	Scaffold a complete new module (invokes @scaffolder)
generate-tests	Run existing tests, then generate missing ones
review-changes	Review staged/uncommitted changes before commit
sync-docs	Update all documentation to match the current code
security-audit	Run a full OWASP-aligned security audit
upgrade-deps	Check and upgrade Composer + npm dependencies
format-code	Run PHP and JavaScript formatters
refactor-code	Analyze and refactor code for health
deploy	Execute safe deployment with verification

---

Cross-Tool Compatibility

AGENTS.md is the universal context file — a single source of truth read by all major AI coding tools:

Tool	Context File	Instructions	Agents	Prompts
GitHub Copilot	AGENTS.md (auto)	.github/copilot-instructions.md (auto) + .github/instructions/ (auto)	.github/agents/	.github/prompts/

Key insight: Write your architecture rules, conventions, and tech debt in AGENTS.md once. Every AI tool picks it up automatically. Tool-specific features (Copilot agents, prompts, file-type instructions) layer on top.

---

Architecture Patterns Demonstrated

This setup demonstrates patterns you can adapt for any Laravel project:

Pattern	How it works
Service layer	All business logic in app/Services/, thin controllers that validate → call service → return response
File-type instructions	Different AI rules for controllers vs models vs migrations — each file type gets contextual guidance
Permission middleware	Convention-driven RBAC with Spatie: can-{view|create|edit|delete}-{resource}
Activity logging	Manual logging via activity() helper — granular control, no observers
Translation conventions	Key patterns for all user-facing strings: __('message.custom.resource.action.outcome')
Tech debt tracking	Known issues documented in AGENTS.md — AI knows about them and fixes properly instead of working around
Cross-tool context	Single AGENTS.md feeds all AI tools; tool-specific files layer on top

---

Stack This Was Built For

Layer	Technology
Framework	Laravel (any version) / PHP 8.1+
Frontend	Inertia.js + Vue.js + Tailwind CSS
Auth (web)	Laravel Breeze (session)
Auth (API)	Laravel Sanctum (token)
RBAC	Spatie laravel-permission
Audit	Spatie laravel-activitylog
Login tracking	Rappasoft laravel-authentication-log
Breadcrumbs	Diglactic laravel-breadcrumbs
DB	SQLite (dev) · MySQL (prod)

Important: These files contain conventions from this specific stack. You must adapt them to your project. See What to Customize below.

---

What to Customize

These are not drop-in configs — they encode a specific project's architecture and conventions. Every organization must adapt them to match their own:

Global Instructions (.github/copilot-instructions.md)

Update Stack section with your actual technology:

## Stack
- **Framework**: Laravel / PHP 8.1+          ← Your framework + version
- **Frontend**: Inertia.js + Vue.js          ← Your frontend framework
- **Auth web**: Laravel Breeze               ← Your auth method
- **RBAC**: Spatie laravel-permission        ← Your permission library
- **DB**: SQLite (dev), MySQL (prod)         ← Your databases

Update Architecture Rules to match your actual patterns:

## Architecture Rules

### Service Layer (mandatory)
- All business logic in `app/Services/`     ← Your directory
- Services extend `BaseService`              ← Your base class
- All services implement `model(): string`   ← Your pattern

Update Directory Map to reflect your project structure.

Update Code Conventions with your actual naming and patterns.

File-Type Instructions (.github/instructions/)

For each instruction file, update the code examples to match your actual code style and patterns:

• laravel-controllers.instructions.md — Update controller examples with your patterns
• laravel-services.instructions.md — Show YOUR service structure, not the template's
• laravel-models.instructions.md — Use YOUR model naming and relationships
• laravel-migrations.instructions.md — YOUR column naming, timeframe strategies
• laravel-seeders.instructions.md — YOUR seeder structure and data sources
• laravel-routes.instructions.md — YOUR route groups, naming conventions
• laravel-lang.instructions.md — YOUR translation key structure
• laravel-tests.instructions.md — YOUR test organization and assertions
• vue-inertia.instructions.md — YOUR component hierarchy and patterns

Example: If your controllers use a BaseController instead of inline logic, show that in the example.

Agents (.github/agents/)

Customize each agent for your team's workflow:

• scaffolder.agent.md — Your module generation process and naming
• code-reviewer.agent.md — YOUR code standards, not generic ones
• tester.agent.md — YOUR test patterns and organization
• deployer.agent.md — YOUR deployment environment and steps
• Others — Adapt to your needs, delete if unused

AGENTS.md (Root Context File)

This is your authoritative architecture guide. Update:

1. Architecture section with your actual patterns
2. Directory Map with your project structure
3. Key Conventions with your team's rules
4. Adding a New Module checklist tailored to your process
5. Known Technical Debt with YOUR actual issues (not generic examples)
6. Do Not section with your team's actual anti-patterns

Checklist for Customization

Essential changes before using agents:

• Update copilot-instructions.md Stack section with your actual stack
• Update Architecture Rules section to match your patterns
• Update Directory Map to match your actual project structure
• Update all .github/instructions/*.instructions.md files with YOUR code examples (not templates)
• Update AGENTS.md with your architecture and conventions
• Add your project's Known Technical Debt to AGENTS.md
• Review and customize each .github/agents/*.agent.md file for your workflow
• Delete agents you don't use
• Test with one agent (@code-reviewer is a safe start) to verify customization

Why This Matters

AI agents work best when they understand YOUR project's specific rules. Generic instructions lead to:

❌ Code that doesn't match your architecture
❌ Suggestions that contradict your conventions
❌ Agents that reference non-existent patterns
❌ False positives in code reviews and audits

With proper customization:

✅ Generated code matches your standards
✅ Agents understand your technical debt and work around it
✅ Code reviews enforce YOUR conventions
✅ Automated tasks save actual time

---

FAQ

Do I need all 9 agents?

No. Start with 2-3 that match your workflow (e.g., @scaffolder + @tester + @code-reviewer) and add more as needed. Delete the ones you don't use.

Does this work with projects other than Laravel?

The structure works for any project. The file hierarchy (global instructions → file-type instructions → agents → prompts) is framework-agnostic. Replace the Laravel-specific content with your stack's conventions.

What's the difference between AGENTS.md and copilot-instructions.md?

AGENTS.md is the full architecture reference read by all AI tools. copilot-instructions.md is a compact subset auto-loaded by GitHub Copilot on every interaction. Keep AGENTS.md as the source of truth and derive copilot-instructions.md from it.

Do agents work in VS Code only?

Agents (.github/agents/) and prompts (.github/prompts/) are GitHub Copilot features — they work in VS Code and GitHub.com. AGENTS.md and instruction files work across all supported AI tools.

How do I add a new file-type instruction?

Create a file in .github/instructions/ with the .instructions.md extension and add YAML frontmatter with an applyTo glob pattern. See the setup guide for the full format.

---

Contributing

Contributions are welcome and encouraged. If you have:

• Better patterns for Laravel-specific agents
• Additional instruction files (e.g., Livewire, Filament, API Resources, Queues)
• Prompt templates for common Laravel tasks
• Improvements to the setup guide
• Agents for other frameworks (adapt the structure)

Please open a PR.

Ideas for Contributions

• Framework-specific agents — Livewire, Filament, Nova instruction files
• Additional prompts — Database optimization, API versioning, queue management
• Language expansions — Translate agents and prompts for multilingual teams
• CI/CD integration — Agents that work with GitHub Actions workflows

---

Links

• Setup Guide: docs/copilot-agentic-setup-guide.md (start here)
• Root Context: AGENTS.md (architecture reference for all AI tools)

---

License

MIT — Use freely, modify as needed, contribute back if you can.

---

Built by Nondito Soft. Extracted from a production Laravel project.