Laravel Junie Laravel Package

Getting Started

Install the package as a dev dependency — it has no runtime role in your application:

composer require dcblogdev/laravel-junie --dev

Then invoke the installer command to publish the guideline documents into your project (typically under .junie/):

php artisan junie:install

If the command name differs, run php artisan list and look for a junie: namespace after install. Some versions use vendor:publish --tag=junie.

Where to look first:

1. .junie/ in your project root — the published guideline documents (usually guidelines.md plus supporting files)
2. config/junie.php — if a config was published, this controls which guideline sets or variants get installed
3. vendor/dcblogdev/laravel-junie/src/ — the service provider and command source; useful to see exactly what paths are written
4. vendor/dcblogdev/laravel-junie/resources/ — the actual markdown templates you can diff against your own edits

First use case: After installing, open your project in a JetBrains IDE with Junie enabled, and ask Junie something like “Read the guidelines in .junie/ and scaffold a new Eloquent model with a factory and feature test.” You should see it follow the Laravel conventions the packaged guidelines enforce (naming, test structure, directory layout) instead of generic PHP patterns.

Implementation Patterns

Install early, before agent-facing work. Run the installer immediately after laravel new or after cloning an existing project, so the first Junie session is already primed. Doing it later means Junie has already “learned” bad assumptions from the raw codebase.

Commit .junie/ to the repository. These are team-shared conventions, not personal config. Every developer (and CI-driven agent runs, if any) benefits from the same baseline. Treat them like .editorconfig — versioned, reviewed, and expected to change with the codebase.

Layer project-specific rules on top of the packaged baseline. Don’t edit the packaged file in place. Instead, append a clearly marked section to the relevant guideline file:

## Project-Specific Conventions
- All HTTP controllers live under `app/Http/Controllers/Api/V1/`
- Use `App\Support\Money` for any monetary value; never use raw floats
- Feature tests use `RefreshDatabase`; unit tests never touch the DB

This preserves the ability to re-pull upstream updates without losing your additions.

Keep parallel agent configs in sync. If your team also uses Claude Code (CLAUDE.md), Cursor (.cursorrules), or generic AGENTS.md, generate them from the same source of truth. The easiest pattern is: keep .junie/guidelines.md as canonical, and make the other files short stubs that say “See .junie/guidelines.md.” Otherwise you get four documents that disagree, and each agent behaves differently on the same PR.

Refresh after upstream releases. When you bump the package version, diff the new template against your committed copy:

composer update dcblogdev/laravel-junie
# inspect what changed in vendor/.../resources/guidelines.md

Merge only the sections that make sense. Blind re-installs will silently overwrite your project-specific additions.

Use module-level guidelines for monorepos. For a multi-app or modular Laravel monorepo, publish the base .junie/guidelines.md at the root, then drop additional .junie/rules/*.md files inside each module with its own conventions. Junie reads hierarchically in most agent implementations; verify the discovery path on your IDE version before relying on it.

Pair with prompts, not just files. The guidelines are static context. For recurring workflows (e.g., “create a new controller with a FormRequest, policy, and feature test”), store the prompt in .junie/prompts/ and reference it. This is not a package feature per se, but it’s the natural extension point once you have the guidelines in place.

Gotchas and Tips

The guidelines are not enforced. They are markdown that Junie reads — nothing stops a developer, a PR, or Junie itself from violating them. If a rule actually matters (e.g., “never log PII”), back it with a linter, PHPStan rule, or architecture test. Guidelines are for judgment calls; static analysis is for hard rules.

Re-running the installer overwrites edits. The junie:install command almost certainly rewrites the guideline files. Back up or commit before re-running, then diff. If your customizations are extensive, consider forking the package's resource templates into your own resources/junie/ and pointing config at them.

.junie/ should be committed, not ignored. A surprisingly common mistake is adding it to .gitignore because “it’s an IDE thing.” Every check-out should carry the same guidelines; a per-developer install defeats the purpose.

Config quirks depend on the version. The package has iterated on file names and directory layout (Junie’s own convention has shifted between IDE releases). If .junie/guidelines.md isn’t being picked up, check: (a) the JetBrains IDE version, (b) the exact filename/dir Junie expects in that version, (c) whether your project root is where the IDE considers “the workspace” (relevant for monorepos — the IDE may only read from the top-level module). A quick sanity check is to ask Junie directly: “Which guideline files have you loaded?”

Use --dev. The package registers a service provider and a command. In production builds you don’t want either. require-dev keeps it out of your deployed artifacts.

Extension points to know about:

• Config file (config/junie.php) — for overriding target paths or selecting guideline variants, if the package exposes them.
• Published templates — you can replace the packaged markdown with your own set by publishing and editing.
• Service provider — for exotic setups (custom guideline locations, conditional installation based on env), you can extend or swap it in AppServiceProvider.
• Command — inspect vendor/.../Commands/ for the exact write behavior; wrapping it in your own artisan command is a clean way to inject post-install hooks (e.g., appending your project-specific section automatically).

Debugging when Junie “ignores” the guidelines. Work outward: (1) confirm the file exists on disk at the expected path; (2) confirm it’s non-empty and well-formed markdown (a stray unclosed code fence can swallow the rest of the file); (3) confirm the IDE has indexed the project (reload the project); (4) ask Junie to echo back the first line of the guidelines — if it can, the file is loaded and the issue is prompt framing, not discovery.

Don’t rely on it for security review. The packaged guidelines target Laravel conventions. They are not a substitute for a security audit or for tooling like enlightn. Treat Junie’s output the same as any AI-generated code: review every diff, especially around auth, authorization, and raw SQL.