# Ticket Implementation Guide

This guide describes how to implement release tickets in this repository.

## Branching

- Use exactly one branch per ticket.
- Use the branch format `codex/<release-name>/<ticket-slug>`.
- For release `v0.5-webhook-notification`, branch names must look like `codex/v0.5-webhook-notification/01-notification-action-foundation`.
- The first ticket branch starts from the release base branch chosen by the maintainer.
- Every later ticket branch starts from the previous ticket branch:
  - ticket 02 branches from ticket 01
  - ticket 03 branches from ticket 02
  - ticket 04 branches from ticket 03
  - continue this pattern until the release is complete
- Do not mix multiple release tickets in one branch.

## Implementation Flow

- Read the ticket completely before changing files.
- Keep the implementation limited to the ticket scope.
- Preserve existing UI, API, and MCP behavior unless the ticket explicitly changes it.
- Follow existing project conventions before introducing new patterns.
- Use actions or services for reusable business logic.
- Use FormRequest classes for request validation.
- Keep app-specific frontend types under `resources/js/types`; do not define them inside `.vue` files.
- Generate Wayfinder output when frontend-facing routes or controllers change.

## Finishing A Ticket

Each ticket must end with:

- Relevant automated tests for the changed behavior.
- Formatting and code generation required by the files changed.
- `git diff --check`.
- `git add` for only the ticket's intended files.
- One commit with a concise ticket-specific message.
- `git push origin <branch-name>`.

Do not leave partially staged work for the next ticket. The next ticket should start from the pushed branch of the completed ticket.

## Verification Defaults

- PHP changes: run `vendor/bin/pint --dirty --format agent`.
- Laravel behavior changes: run targeted `php artisan test --compact ...`.
- Route or frontend controller changes: run `php artisan wayfinder:generate --with-form --no-interaction`.
- Vue or TypeScript changes: run `npm run types:check`.
- Documentation-only changes: `git diff --check` is enough unless the ticket says otherwise.