Save this content to: .claude/skills/laravel-auditor-development/SKILL.md

# Laravel Auditor Development

Use this skill when a Laravel application needs to install, configure, or apply the Laravel Auditor package. Auditor does not scan the app. After setup, the user asks their AI agent to use the `laravel-audit` skill.

## Primary goals

- Install Laravel Auditor as a development dependency.
- Run the appropriate setup command (Boost-based or standalone).
- Verify setup with the diagnostics command.
- Use the audit workflow skill to perform an audit.

## Workflow

### 1. Install the package

```bash
composer require --dev mrpunyapal/laravel-auditor
```

### 2. Set up resources

When Laravel Boost is installed, expose Auditor resources through Boost:

```bash
php artisan boost:install
```

(or `php artisan boost:update` after package updates).

When Boost is not installed, use the standalone installer:

```bash
php artisan auditor:install --agents=claude_code
php artisan auditor:install --agents=claude_code,opencode
```

The installer is idempotent and safe. It detects the Laravel application context, detects whether Boost is installed, prepares Auditor's agent-facing resources, and reports what it created or updated.

Non-interactive runs resolve agents from `--agents`, then `laravel-auditor.agents`, then project markers. When none of those resolve, no agents are wired. A `.github` directory alone is not treated as Copilot. Unknown `--agents` values warn and are skipped. To wire an agent that is not in the built-in list, add it under `laravel-auditor.custom_agents`. Pass `--force` to refresh Auditor-owned resources, including an existing `laravel-auditor` MCP entry.

### 3. Verify setup

```bash
php artisan auditor:status
```

### 4. Inspect the available rules and project facts

```bash
php artisan auditor:rules
php artisan auditor:context --list
php artisan auditor:context project_info
```

### 5. Run an audit

Ask the agent to use the `laravel-audit` skill to perform a structured, evidence-based audit of the application.

### 6. Render a report

If the agent produced a JSON findings file:

```bash
php artisan auditor:report --example
php artisan auditor:report --findings=storage/auditor-findings.json --format=markdown
```

Supported formats: `markdown`, `json`, `text`, `sarif`. Finding schema: publish tag `laravel-auditor-schema`.

### 7. Optional MCP

```bash
php artisan auditor:mcp -q
```

Register that stdio command with the agent so it can call `project_info`, `routes`, `models`, `migrations`, `database_schema`, `dependencies`, `configuration`, `policies_authorization`, `jobs_events_schedules`, `tests`, `subsystems`, `changed_files`, and `review_scope`. Use `-q` so Artisan boot output cannot break MCP stdio framing.

With Laravel Boost installed, the same context tools are registered automatically inside Boost's MCP server (via `boost.mcp.tools.include`); no extra setup is needed.

## References

- Install: `composer require --dev mrpunyapal/laravel-auditor`
- Boost path: `php artisan boost:install` / `php artisan boost:update`
- Standalone path: `php artisan auditor:install` (`--dry-run`, `--force`, `--agents=`)
- Diagnostics: `php artisan auditor:status`
- Rules: `php artisan auditor:rules` (`--domain=`, `--json`, `--applicable`)
- Context: `php artisan auditor:context` (`--list`, `{collector}`, `--output=`)
- Reports: `php artisan auditor:report` (`--findings=`, `--example`, `--format=markdown|json|text|sarif`, `--output=`, `--base=origin/main`, `--dirty`)
- CI: `php artisan auditor:ci --findings=storage/auditor-findings.json --base=origin/main --fail-on=high` (`--base` gates the committed diff; `--dirty` gates only uncommitted work and matches nothing on a clean checkout)
- Facade: `LaravelAuditor::collect('routes')`, `LaravelAuditor::rules()`, `LaravelAuditor::context()`, `LaravelAuditor::project()`
- Config: `resources_target`, `agents`, `custom_agents`, `context.composer_audit` (on), `context.test_listing` (off), `changed_files.include_untracked`, `changed_files.ignore`, `changed_files.max_files`
- Config publish tag: `laravel-auditor-config`
- Resource publish tag: `laravel-auditor-resources`
- Schema publish tag: `laravel-auditor-schema`
- Example publish tag: `laravel-auditor-examples`
- Audit workflow skill: `laravel-audit` (`laravel-audit-dsa` for subsystem / P0–P3 ranking)

## Examples

Ask the agent:

> Use the laravel-audit skill. Call `review_scope` first and audit the dirty files plus the views, tests, and classes they directly use. Report only findings with file, route, or schema evidence.

A finding should include `rule_id`, `severity`, `confidence`, `summary`, `why_it_matters`, `evidence`, and `recommendation`.

Default audit prompt:

> You are auditing the Laravel application in this project using the Laravel Auditor methodology.
>
> 1. Use the laravel-audit skill. Follow its Discover → Scope → Verify → Report workflow.
> 2. Call `review_scope` first. When `scope` is non-empty, audit those files only: the dirty files and the views, tests, and classes they directly use. Do not pull the full route, model, or schema inventory.
> 3. When `changed` is empty, say the working tree is clean. Audit the whole application only if the user asked for that.
> 4. Scope the relevant domains (security, database, architecture, testing, ...). Pick the domains with the most risk signal and go deep.
> 5. For every potential finding, verify against actual files, routes, or schema. Never report a guess.
> 6. Report findings ranked P0–P3, each with: file/route/schema evidence, the rule violated, why it matters, and a concrete fix.
> 7. Be read-only. Do not modify any application code.

Whole-application prompt:

> Audit the whole application, including files outside the dirty scope. Use the laravel-audit skill, gather the context tools, and report only evidenced findings.

Discover-only quick pass:

> Start with a Discover phase only: run all 13 context tools, summarize what this app is (framework versions, database, route surface, model list, test coverage), and flag any immediate red flags in 3-5 bullets. Do not write findings yet.

## Anti-patterns

- Do not require Boost just to use Auditor.
- Do not run `php artisan auditor:install` when Boost is installed unless a standalone path is explicitly wanted.
- Do not modify application code during setup or during an audit.
- Do not treat Auditor as an autonomous scanner that invents findings without evidence.