Download the PHP package robertogallea/laravel-necromancer without Composer

Laravel Necromancer

Laravel Necromancer scans your bootstrapped Laravel application and builds a structured, machine-readable inventory called the manifest. From that manifest you can display a terminal map of your application, run an AI-readability audit, and generate a Markdown context file that AI coding agents can load as ambient context — so they always have an accurate picture of your routes, models, jobs, events, observers, scheduled tasks, middleware, Livewire components, gates, mailables, validation rules, service providers, and more.

What Necromancer Collects

The manifest covers 18 artifact types across the full Laravel application structure:

All artifact types carry a source field with file, line, line_end, and hash for precise citations and stale detection.

Requirements

Installation

Install the package as a development dependency:

The service provider is auto-discovered — no manual registration is needed.

Optionally publish the configuration file:

Usage

Necromancer follows a scan-first workflow. Every other command reads the manifest produced by necromancer:scan rather than re-scanning the application.

Step 1 — Scan

Inspects the running application and writes necromancer.json to the project root. Re-run this command whenever your application changes. Collect only specific artifact types with --only:

Necromancer reads PHP attributes (#[ObservedBy], #[Queue], #[Aliases], #[Authorize], etc.) as primary sources alongside class properties. Codebases using the attribute-based API introduced in Laravel 11+ are fully supported — jobs configured via #[Queue]/#[Tries]/#[Timeout], models with #[ObservedBy]/#[ScopedBy], and commands with #[Aliases] all appear correctly in the manifest.

Test files in tests/Unit/ and tests/Feature/ are scanned and included as a tests artifact type. Both Pest functional-style files (test()/it() calls) and class-based PHPUnit tests are supported. Subject classes are inferred from uses() declarations and filename convention (OrderTest.php → App\Models\Order).

Check for manifest drift without writing a new file (CI use):

Step 2 — Explore (optional)

Display the full application inventory in the terminal:

Narrow the output to a single artifact type:

Step 3a — Audit AI readability

Check how well your application can be understood by an AI coding agent:

Each finding is grouped by severity (error / warning / suggestion). The score is a weighted pass-rate across all checks — normalized by the number of applicable artifacts — so an app with 1 unnamed route out of 50 scores far better than one with 1 out of 1. Errors weigh 3×, warnings 2×, and suggestions 1× in the calculation. Output a shareable or machine-readable report, or enforce a CI gate:

Step 3b — Check the AI readability score

Get a quick percentage score across seven weighted dimensions of AI readability:

Each dimension shows a progress bar, a percentage, and a detail line:

Output a machine-readable score or enforce a CI gate:

Step 3c — Generate AI context

Write a Markdown context file your AI tool can load:

Produces NECROMANCER.md at the project root. The generated file includes a ## Tests table when test artifacts are present:

Generate only specific sections:

Supported types: routes, models, form_requests, jobs, events, listeners, commands, policies, enums, tests, observers, scheduled_tasks, middleware, livewire_components, gates, mailables, validation_rules, service_providers.

Exclude specific sections instead of listing everything you want:

--only and --except are mutually exclusive.

Filter by source path to generate context for just one slice of the application:

--paths matches each artifact's source.file by path prefix (after normalizing slashes) and is applied on top of --only/--except, so it can be combined with either. Paths are case-sensitive on Linux and case-insensitive on macOS/Windows, following the filesystem. Artifacts without a source file (closure routes, inline gates) are excluded while --paths is active, sections that end up empty are omitted, and a path that matches nothing emits a warning without failing.

Skip the overwrite confirmation when regenerating:

Write to a custom path:

Step 3d — Ask a question about your codebase

Ask a natural-language question and get a grounded answer from your manifest:

If you omit the question, the command prompts you interactively. The manifest is injected verbatim into the AI's context, so answers are grounded in your actual application — not a model's prior knowledge. A warning is shown if the manifest may be stale.

Requires laravel/ai installed and an AI provider configured in config/ai.php.

Inspect the AI payload

Before committing to a provider, check exactly what Necromancer sends to the AI and how large the payload is:

Prints the full manifest JSON, the estimated token count, and a breakdown of artifact type counts. Pass --privacy to see the condensed privacy-safe summary instead (the payload used when a privacy-conscious provider is configured):

Step 3e — Infer Architecture Decision Records

Generate Architecture Decision Records from the manifest using an AI provider:

Requires laravel/ai installed and an AI provider configured in config/ai.php.

Options

Output

ADRs are written to docs/adr/necromancer/ (canonical locale, flat) and docs/adr/necromancer/{locale}/ for each translated locale. Each file follows the Nygard ADR format:

Decision Taxonomy

The inference agent evaluates nine architectural dimensions and produces at most one ADR per dimension:

Critic Agent

By default, a second AI pass reviews and filters the initial ADRs, removing generic observations and improving specificity. Configure via config/necromancer.php:

Use --max-critic-rounds=N to run up to N review passes. The critic signals when it is satisfied; the loop exits early even if N has not been reached. Each unsatisfied round adds one AI call.

Caching

The command caches inference results in docs/adr/necromancer/.adr-inference-cache.json. The cache key is derived from meta.content_hash (a SHA-256 of the artifact payload written into every manifest by necromancer:scan), plus the temperature and critic settings. Because the hash covers only artifact data — not the scan timestamp — the cache survives re-scans that find no structural changes. On subsequent runs:

• Unchanged codebase — cached ADRs are used even if necromancer:scan was re-run; no AI call.
• New --locale added — only the translation call is made; inference is skipped.
• --refresh — forces re-inference with an unchanged manifest.
• --fresh — clears the cache and all ADR files before re-inferring.

Multi-Locale Workflow

Step 3f — Generate a source-grounded prompt

Build a ready-to-paste AI prompt grounded in the most relevant manifest entries for your question:

Necromancer keyword-searches the manifest, ranks artifacts by relevance, and outputs a formatted prompt block with file:line citations that you can paste into any AI tool (Claude, ChatGPT, Cursor, etc.).

If laravel/ai is installed, the question is automatically reformulated into a precise, application-aware version before being included in the prompt. Pass --no-ai to use the raw question instead.

AI reformulation requires laravel/ai installed and configured. The command works without it — only the question contextualization step is skipped.

Step 3g — Compare manifests across branches

Review the architectural changes introduced by a branch compared to another:

Compares the current manifest against the manifest on the main branch. The output shows added, removed, and modified routes, models, jobs, events, listeners, policies, and other artifacts.

Options

Example: Basic diff

Output:

Example: AI-powered review

Output (when laravel/ai is installed):

Note: The --review option requires laravel/ai to be installed and configured. Without it, only the basic diff is shown. Both branches must have a committed necromancer.json manifest.

Step 3h — Benchmark AI context effectiveness

Measure how much Necromancer's generated context file improves AI coding-assistant accuracy, hallucination rate, and token cost compared to a hand-written AGENTS.md or no context at all:

The command runs a bundled task suite in three conditions — no context, manual AGENTS.md, and Necromancer-generated NECROMANCER.md — and reports the results side by side. An optional cross-model AI judge scores quality; automated fact-checks always run.

Q&A tasks (which measure context coverage) only run under the none and manual conditions — Necromancer would trivially score 100% since the answers are in the context file it generated. Code generation and mini tasks run across all three conditions and measure actual effectiveness.

See BENCHMARK.md for full setup instructions, config reference, and bias mitigations.

Commands Reference

Configuration

After publishing the config, edit config/necromancer.php:

Privacy & Exclusions

Necromancer is designed to be safe to version by default:

• It never reads .env or raw configuration values.
• It never collects or stores application secrets.
• Routes registered by Horizon, Telescope, and Debugbar are excluded from scans automatically.
• Laravel's default /up health-check endpoint is excluded automatically via exclude.route_uris, so it never shows up as an unnamed-route audit finding.

To exclude additional routes or models, add patterns to the exclude key in config/necromancer.php. The exclude.routes patterns match against the route name (and therefore never match unnamed routes); use exclude.route_uris to exclude routes by URI — including unnamed ones such as health checks. Both use Str::is() wildcard matching, and route URIs are matched without a leading slash (e.g. up, orders/*). Exclusions apply to every downstream command — map, audit, doctor, and generate — so excluded artifacts never appear in results.

Laravel Boost Integration

When Laravel Boost is installed, necromancer:generate automatically writes the context file to .ai/guidelines/necromancer.md (configurable via boost.context_path) instead of NECROMANCER.md. Boost remains responsible for composing the final agent context; Necromancer only contributes its section.

An explicit --output=PATH flag always takes precedence over the Boost path.

MCP Tools

When Laravel MCP is installed, Necromancer automatically exposes the manifest as read-only MCP tools via a laravel-necromancer server handle:

Use query_artifacts when you already know the artifact type (routes, models, form_requests, jobs, events, listeners, commands, observers, policies, enums, tests, scheduled_tasks, middleware, livewire_components, gates, mailables, validation_rules, or service_providers). Use search_artifacts when you need to search across types.

When laravel/mcp is present, Necromancer also writes its entry into .mcp.json automatically on the first php artisan run after installation — no manual configuration needed. If .mcp.json already exists, the entry is merged without touching other servers.

AI agents connected via Claude Code, Cursor, or any MCP client can then call these tools directly rather than reading necromancer.json by hand.

Requires laravel/mcp installed. Run php artisan necromancer:scan to ensure the manifest is current before connecting an agent.

CI Integration

Add these steps to your CI pipeline to enforce manifest freshness and AI-readability quality:

Contributing

Bug reports and pull requests are welcome on the GitHub repository.

License

MIT