Download the PHP package kngbwsr/laravel-agent-optimizer without Composer

Laravel Agent Optimizer

A Laravel package that optimizes AI agent directive files by extracting large guideline sections into modular rule files, keeping your top-level agent directives lean and focused.

Works seamlessly with Laravel Boost-generated agent directive files and automatically re-runs after configured trigger commands (e.g. boost:update, boost:install).

Features

• Dedicated output folder — all generated files live inside a single agent-optimized/ folder, making cleanup trivial and preventing stale files when config changes
• Automatic section extraction — scans *.md agent directive files for === title === sections and moves qualifying sections to dedicated rule files
• Five extraction strategies — full_section, nested_full, nested_subsections, nested_split, and auto to suit any section structure
• Per-section strategy overrides — apply a different strategy to individual sections without changing the global default
• Configurable line threshold — only extract sections that exceed a minimum line count, filtering out trivial sections
• Configurable file naming — control the prefix and extension for generated rule and subsection files (e.g. .mdc for Cursor IDE)
• Configurable reference pretext — customise the label inserted before every file-path reference, globally or per-strategy; supports a <title> token that is replaced at runtime with the actual section or sub-section title
• Idempotent optimization — an <!-- agent-optimized --> marker is written into each extracted section so standalone re-runs skip already-optimized sections without double-extracting, and the preflight step preserves rule files that are still referenced
• Configurable header notes — automatically prepends an LLM-readable blockquote to agent directive files and to generated rule files; content is fully customisable via config
• Exception list — protect specific sections from ever being extracted
• Dry-run mode — preview what would be extracted without writing any files
• Laravel Boost integration — automatically re-optimizes after configured trigger commands (default: boost:update, boost:install)
• One-step install command — optimizeAgents:install publishes the config and wires up composer.json in a single step
• Reset command — optimizeAgents:reset removes all generated files and re-runs Boost without re-triggering optimization
• Laravel auto-discovery — zero manual registration required for Laravel 13+

Requirements

• PHP 8.2+
• Laravel 13+
• Laravel Boost (required for the optimizeAgents:reset command and auto-run integration)

Installation

Install the package via Composer:

Laravel's auto-discovery will register the service provider automatically.

One-step setup

Run the install command to publish the config file and add the post-update-cmd entry to composer.json in one step:

This does two things:

1. Publishes config/agent-optimizer.php to your application (skipped if already published)
2. Adds @php artisan optimizeAgents:optimize --ansi to the post-update-cmd array in composer.json

To remove the post-update-cmd entry later:

Note: Auto-discovery means the package is fully functional before you run optimizeAgents:install. The command is a convenience for initial project setup only — it combines the config publish and the composer.json edit into a single step.

Output folder

All generated files are written to a dedicated agent-optimized/ folder inside your configured base_path:

On each optimizeAgents:optimize run a smart preflight step runs before any extraction. If the agent files contain sections already marked as optimized the corresponding rule files are preserved; only orphaned or stale files are removed. When agent files are regenerated fresh (e.g. after boost:update) no markers are present and the entire agent-optimized/ folder is wiped and recreated.

Configuration

After running optimizeAgents:install (or php artisan vendor:publish --tag=agent-optimizer-config), config/agent-optimizer.php exposes the following options:

Paths & file discovery

Generated file naming

Extraction behaviour

Reference pretext labels

Controls the label inserted before every rule file path in placeholder lines.

The special token <title> may be used anywhere in a label string and is replaced at runtime with the actual section or sub-section title (the text between the === ... === markers, without the equals signs). For example, '**RULES for <title>:**' becomes **RULES for My Section:** in the output file.

Example — embedding the title and using custom labels per strategy:

Header notes

Controls the Markdown note prepended to agent directive files and generated rule files when sections are first extracted.

Note: if you change either of these values after files have already been optimized, run php artisan optimizeAgents:reset first so the old header is removed before the new one is written.

Laravel Boost integration

Usage

Basic run

Scans all configured source_directories for agent directive Markdown files, extracts qualifying sections to {base_path}/agent-optimized/, and replaces each extracted block with a configurable reference placeholder.

Preview without writing files

Reports every section that would be extracted without modifying any file.

Override the root directory

Useful when running the command outside the project root.

Override the minimum line threshold

Overrides line_threshold from config for this run only.

Combined example

Reset

Performs a clean reset of the optimizer's output:

1. Deletes the entire agent-optimized/ folder and all files within it
2. Runs the first configured boost_trigger_commands entry (default: boost:update) so Boost regenerates the original agent directive files
3. Does not re-run optimizeAgents:optimize afterwards, even if auto_run_after_boost is true

Use reset when:

• You want to return agent directive files to their unoptimized state
• You have changed structural config options (e.g. base_path, rule_file_prefix) and need a clean slate before re-running
• You are debugging the optimizer's output

How it works

1. Preflight: the command scans agent files for <!-- agent-optimized --> markers. Rule files for already-extracted sections are preserved; orphaned files are deleted. When no markers exist (e.g. after a fresh boost:update) the entire agent-optimized/ folder is wiped and recreated.
2. The command scans each configured directory for *.md files that contain at least one === title === section boundary.
3. Each section is parsed and checked against the configured exceptions list and line_threshold. Sections that already carry the <!-- agent-optimized --> marker are skipped.
4. The configured extraction strategy (global or per-section override) determines how the section is extracted:
   • A rule file is written to {base_path}/agent-optimized/ using the configured rule_file_prefix and rule_file_extension.
   • The original section body is replaced with a reference placeholder using the configured pretext label and the file path.
   • The agent_file_header note is prepended to the source agent directive file (once, on first extraction).
   • The rule_file_header note is prepended to each top-level _rule_*.md file (not to _subsection_*.md files).
5. If the source file was modified (or needs a header added) it is written back to disk.

Extraction strategies

Boost integration detail

The auto_run_after_boost listener fires on the CommandFinished event after any command listed in boost_trigger_commands. This keeps extracted rule files in sync whenever Boost regenerates your agent directive files from Artisan.

The post-update-cmd entry added by optimizeAgents:install handles the case where composer update itself triggers a Boost update cycle.

optimizeAgents:reset suppresses the auto_run_after_boost listener for the boost run it triggers, so the reset leaves files in a clean unoptimized state rather than immediately re-optimizing.

License

MIT