Last indexed: 7 March 2026 (397730)

Guidelines and Instructions

This document covers the AI guidelines system that provides context-aware instructions to GitHub Copilot CLI. These guidelines are dynamically generated based on the environment and inform the AI about Laravel Boost capabilities, project structure, and best practices.

For information about MCP server configuration, see MCP Configuration File. For environment detection mechanics, see Environment Detection and Adaptation.

Purpose and Scope

The guidelines system serves as a critical bridge between the Laravel Boost MCP server and GitHub Copilot CLI, providing the AI with:

Instructions on how to properly invoke MCP tools
Environment-specific constraints and capabilities
Laravel version-specific conventions
Code quality standards and testing requirements

This system uses Blade templates to dynamically render guidelines based on the runtime environment, ensuring the AI receives accurate context for its current working environment.

System Overview

Guidelines System Architecture

Sources: resources/boost/guidelines/core.blade.php1-22 .github/workflows/copy-guideline.yml1-27 tests/Feature/GuidelinesTest.php1-71

Core Guideline Template

The guidelines system uses a Blade template located at resources/boost/guidelines/core.blade.php. This template contains environment-aware instructions that are rendered differently based on runtime context.

Template Structure

Section	Purpose	Environment
MCP Configuration File Required	Instructs users to restart Copilot CLI with correct MCP config	All
Laravel Package Development Environment	Warns about Testbench limitations and tool availability	Testbench only
Foundation Rules	Laravel ecosystem versions and core guidelines	All
Boost Rules	Laravel Boost MCP tool usage instructions	All
PHP Rules	PHP 8+ conventions and type hints	All
Laravel Rules	Framework-specific conventions	All
Pint Rules	Code formatting requirements	All
Pest Rules	Testing framework conventions	All

Sources: resources/boost/guidelines/core.blade.php1-22

Blade Conditional Rendering

The template uses the @if(defined('TESTBENCH_CORE')) directive to conditionally include environment-specific sections. This allows the same template to serve both standard Laravel applications and package development environments.

Conditional Logic Flow

Sources: resources/boost/guidelines/core.blade.php11-21 tests/Feature/GuidelinesTest.php40-70

Environment-Specific Guidelines

The guidelines system adapts its output based on two primary environments:

Standard Laravel Application Environment

When running in a standard Laravel application, the guidelines assume:

Full application context with database, models, and routes
All Laravel Boost MCP tools are available
Standard php artisan commands work
Application-specific features can be accessed

The rendered guidelines in this environment include only the base instructions without Testbench-specific warnings.

Sources: resources/boost/guidelines/core.blade.php1-10 tests/Feature/GuidelinesTest.php40-51

Orchestra Testbench Environment

When TESTBENCH_CORE is defined, additional warnings are rendered to inform the AI about environment limitations:

Testbench Limitations Section

The guidelines explicitly state:

This is a package development project, not a standard Laravel application
No full application context, database, or application-specific models exist
Tools like database-query, database-schema, list-routes may fail or return limited results
Basic tools like application-info, list-artisan-commands, search-docs should work normally
Developers should use vendor/bin/testbench instead of php artisan

This prevents the AI from attempting operations that will fail in the limited Testbench environment.

Sources: resources/boost/guidelines/core.blade.php11-21 tests/Feature/GuidelinesTest.php53-70

Generated Instructions File

During the boost:install command, the CopilotCli agent generates the instructions file at .github/instructions/laravel-boost.instructions.md.

File Generation Process

Sources: tests/Feature/GuidelinesTest.php9-13 resources/boost/guidelines/core.blade.php1-22

Generated File Structure

The generated .github/instructions/laravel-boost.instructions.md file contains:

XML Wrapper: Content wrapped in <laravel-boost-guidelines> tags
Section Markers: Guidelines organized with === .ai/copilot-cli rules === headers
Rendered Markdown: Fully rendered Blade output with conditionals resolved
Framework Guidelines: Complete Laravel, PHP, Pest, and Pint conventions

File Layout

Line Range	Content	Purpose
1	`<laravel-boost-guidelines>`	XML opening tag
2	`=== .ai/copilot-cli rules ===`	Section marker
3-25	Copilot CLI specific instructions	MCP config and environment warnings
26+	Foundation, Boost, PHP, Laravel rules	Complete guideline set
End	`</laravel-boost-guidelines>`	XML closing tag

Sources: .github/instructions/laravel-boost.instructions.md1-254

Synchronization Workflow

The package maintains a synchronized copy of the guidelines template in the .ai/guidelines/ directory for backward compatibility or alternative consumption patterns.

GitHub Actions Workflow

The copy-guideline.yml workflow automatically synchronizes the template:

Sources: .github/workflows/copy-guideline.yml1-27

Workflow Configuration

The workflow is configured at .github/workflows/copy-guideline.yml1-27 with:

Trigger: Push to main branch with changes to resources/boost/guidelines/core.blade.php
Permissions: contents: write for committing changes
Actions:
- actions/checkout@v6 for repository access
- stefanzweifel/git-auto-commit-action@v5 for automatic commits
Copy Operation: Line 19 performs the file copy
Commit Options: --no-verify to bypass git hooks

Sources: .github/workflows/copy-guideline.yml4-26

How Copilot CLI Consumes Guidelines

GitHub Copilot CLI reads the generated instructions file to provide context to the AI model during every interaction.

Consumption Flow

Sources: resources/boost/guidelines/core.blade.php1-10 .github/instructions/laravel-boost.instructions.md1-13

Critical Instructions

The guidelines provide several critical instructions that affect AI behavior:

MCP Configuration Reminder (.github/instructions/laravel-boost.instructions.md3-13)

If MCP tools are not visible, instruct user to restart with --additional-mcp-config @.github/mcp-config.json --continue
This option is required for every Copilot CLI session

Testbench Environment Warnings (.github/instructions/laravel-boost.instructions.md15-24)

Explains this is a package development environment with limitations
Lists which MCP tools may not work correctly
Guides AI to focus on package-specific development tasks

Skill Activation (.github/instructions/laravel-boost.instructions.md46-50)

Instructs AI to activate the pest-testing skill when working with tests
Ensures proper test framework usage

Sources: .github/instructions/laravel-boost.instructions.md1-254

Testing the Guidelines System

The package includes comprehensive tests for the guidelines system at tests/Feature/GuidelinesTest.php.

Test Coverage

Test Name	Validates	Lines
`guidelines file exists`	Template file presence	9-13
`guidelines contain GitHub Copilot CLI section`	Required content sections	15-21
`guidelines contain MCP config restart instruction`	Critical MCP config instructions	23-29
`guidelines contain testbench section`	Blade conditional directives	31-38
`guidelines render correctly without testbench`	Standard environment rendering	40-51
`guidelines render correctly with testbench`	Testbench environment rendering	53-70

Rendering Test Pattern

The tests use Blade::render() to validate template rendering in both environments. For Testbench testing, the tests define the TESTBENCH_CORE constant before rendering to simulate the package development environment.

Sources: tests/Feature/GuidelinesTest.php1-71