Lawman Laravel Package

Getting Started

Lawman generates a Markdown "context" file that describes your Laravel application's structure — models, relationships, controllers, routes, commands and so on — so an AI assistant (Claude Code, Cursor, Copilot) can reason about your codebase without crawling it every time. It is a development tool, not a runtime dependency.

1. Install as a dev dependency:

   composer require jonpurvis/lawman --dev
   

2. Publish the config:

   php artisan vendor:publish --tag="lawman-config"
   

3. Generate the file:

   php artisan lawman:generate
   

Look first at config/lawman.php — it controls which sections are emitted and where the output lands. Everything you'll want to tune lives there.

First use case: run the command once on an existing app, skim the generated Markdown to confirm it captured the pieces you care about, then point your AI tool at it (e.g. reference it from CLAUDE.md, .cursor/rules, or paste it into a fresh chat). The immediate win is that you stop re-explaining "we use action classes, money is stored in minor units, Order has a state machine" in every session.

Implementation Patterns

Commit the generated file, regenerate deliberately. Treat it like documentation, not a build artifact. Regenerating on every save produces noisy diffs and burns tokens re-reading unchanged sections. A good rhythm is: regenerate at the start of a feature branch, commit alongside the work, and let reviewers see the architectural delta.

Regenerate as a Composer script. Wire it to something explicit rather than automatic:

"scripts": {
    "lawman": ["@php artisan lawman:generate"]
}

Then composer lawman after pulling a branch with structural changes. Avoid post-install-cmd — it fires in CI and on every deploy for no benefit.

Scope the config per project. For a large app the default output is enormous. Trim sections you don't need an assistant to know about (e.g. drop migrations once the schema is stable, keep models and routes). The signal-to-noise ratio of the file is the single biggest lever on how useful it is.

Layer project-specific conventions on top. The generated structure tells an assistant what exists; it doesn't tell it how you work. Keep a hand-written CLAUDE.md / conventions doc next to the generated file and reference both — Lawman for the map, your own notes for the rules.

Use it in a modular/monorepo setup by running the generator once per application directory rather than trying to produce one giant file, and keep each output next to the app it describes.

For onboarding, the same file doubles as a genuinely readable architecture summary for a new hire — one of the cheaper wins from adopting the package.

Gotchas and Tips

• Keep it in require-dev. There's no reason for this to be installed in production; a --no-dev deploy will then simply not have it.
• Guard the command in production. If the artisan command is registered, someone will eventually run it on a server. Either accept the harmless output file or wrap it in an environment check in your deploy scripts.
• Clear the config cache after editing config/lawman.php. If you've ever run php artisan config:cache locally, config edits appear to do nothing. This is the most common "it's broken" report.
• Watch for stale output. A context file that no longer matches the code is worse than no file — the assistant will confidently reference classes that were deleted. If you can't commit to regenerating, don't commit the file.
• Output size is the failure mode. On a mature app, the naive config produces a file too large to be useful as context. Start minimal, add sections back only when you notice the assistant asking about something it should have known.
• Pin the version in composer.json. Helpers and output formatting are the parts most likely to shift between minor releases; a floating constraint means your committed file changes shape on a composer update and the diff looks like architecture churn.
• Check .gitignore. The package may or may not ship an ignore entry for the output path — decide intentionally rather than discovering it in a PR.
• Extension points: the config is the primary knob; the v5.2.0 "New Helpers" release points at a growing helper layer for shaping emitted content. If you need a section Lawman doesn't produce, that's the place to look before writing your own generator.
• Debugging: if a section is empty, it's almost always a path/namespace mismatch in the config rather than a bug — verify the value against an actual directory in your app before filing an issue.