Save this content to: AGENTS.md

# Laravibe Standards

This repository is a Laravel package. Keep the package focused, idiomatic, and easy for Laravel developers to install, test, and maintain.

## Package Conventions

- Use Laravel-native package APIs and the existing service provider shape before adding abstractions.
- Keep package names, namespaces, Composer metadata, publish tags, documentation, and examples aligned with `thesoftpulze/laravibe-standards`.
- Add only the files and dependencies needed for the package behavior being implemented.
- Prefer explicit Laravel package code over helper abstractions unless the extension point is real.
- Keep tests focused on observable package behavior through public APIs, service provider wiring, commands, routes, published resources, and documentation promises.

## Package Map

- `src/DTOs`, `src/Enums`, `src/Resources`: the public API (`AsDTO`, `HasEnumMetadata`, `AppResource`, `AppResourceCollection`), each with a `README.md` guide.
- `src/Console/Commands`: the `make:action` and `make:dto` commands. `make:enum` and `make:resource` are Laravel's own commands, customized only through the published stubs.
- `stubs/`: generator stubs, published with the `laravibe-standards-stubs` tag.
- `resources/boost/`: the Boost guideline and skills installed into consuming applications. `tests/Feature/BoostResourcesTest.php` fails if they reference classes, methods, or publish tags that don't exist.

When public behavior changes, update `README.md`, the matching `src/*/README.md`, and the Boost guideline or skills in the same change.

## Quick Commands

- Full validation: `composer test`
- Formatting check: `composer lint:check`
- Static analysis: `composer analyse`
- Pest tests: `composer test:unit`
- Workbench build: `composer build`
- Workbench server: `composer serve`

## Release Conventions

Release notes are auto-generated from PR labels via `.github/release.yml`. Always pass `--label` when running `gh pr create`:

| PR title prefix | `--label` value |
|----------------|-----------------|
| `feat:` or `feat(` | `enhancement` |
| `fix:` or `fix(` | `bug` |
| `docs:` or `docs(` | `documentation` |
| `refactor:`, `chore:`, `style:`, `test:`, `ci:` | `maintenance` |
| `deps:` or dependency bumps | `dependencies` |
| Contains `!:` or `BREAKING CHANGE` | `breaking` + type label |
| Skip changelog | `skip-changelog` |

Example: `gh pr create --title "feat: add resource conventions" --body "..." --label enhancement`

Release commands (run from `main` with clean working tree):

```
composer test
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z
gh release create vX.Y.Z --title "vX.Y.Z" --generate-notes
```

The `update-changelog.yml` workflow fires on release and auto-updates CHANGELOG.md. Note: `--title` is required — without it the workflow fails because `latest-version` is empty.

Do not manually populate `[Unreleased]` in CHANGELOG.md. The workflow handles CHANGELOG entries automatically from the release body generated by `--generate-notes`. Only PR labels and titles drive the changelog content.

## Local Skills

- `package-scaffold`: use when adding package capabilities or wiring them through the service provider, including commands, migrations, routes, config, views, translations, assets, middleware, publish tags, workbench files, and console-only behavior.
- `package-testing`: use when adding or changing package tests with Pest 4 and Orchestra Testbench.
- `package-release`: use when preparing changelog, release notes, tags, or GitHub release workflow changes.
- `package-compatibility`: use when reviewing code, dependencies, or CI against the PHP 8.4+ and Laravel 13+ support matrix.
- `package-generate-skill`: use when updating the bundled Boost guideline or skills from the package implementation, README, and examples.