diff --git a/.github/workflows/skills-validation.yml b/.github/workflows/skills-validation.yml index bc15b17..eb9b2b5 100644 --- a/.github/workflows/skills-validation.yml +++ b/.github/workflows/skills-validation.yml @@ -6,18 +6,26 @@ on: - main pull_request: +env: + # Opt JavaScript-based actions into Node 24 until it is the runner default (see GitHub Actions changelog). + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + jobs: validate: runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + php-version: ['8.4', '8.5'] steps: - name: Checkout code - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Setup PHP uses: shivammathur/setup-php@v2 with: - php-version: '8.4' + php-version: ${{ matrix.php-version }} coverage: none - name: Install dependencies diff --git a/FRONTEND.md b/FRONTEND.md new file mode 100644 index 0000000..74625bf --- /dev/null +++ b/FRONTEND.md @@ -0,0 +1,165 @@ +# Frontend Criteria Checklist + +This document is an execution checklist for `FrontendImplementationAgent`. + +Goal: launch `FrontendImplementationAgent` (or `ImplementationAgent` for mixed scope) and have it run the full frontend workflow end-to-end, not just adjust one or two classes. + +## Agent to Launch + +- Primary: `FrontendImplementationAgent` +- Supporting (if needed): `ImplementationAgent`, `ReviewAgent`, `DocumentationAgent` + +## Skills to Load First + +- Core frontend UI architecture: `design`, `tailwind`, `blade` +- Quality and consistency: `general` +- Domain-specific (based on touched files): `livewire`, `resources`, `translations` + +Skill file references: + +- `resources/boost/skills/design/SKILL.md` +- `resources/boost/skills/tailwind/SKILL.md` +- `resources/boost/skills/blade/SKILL.md` +- `resources/boost/skills/general/SKILL.md` +- `resources/boost/skills/livewire/SKILL.md` +- `resources/boost/skills/resources/SKILL.md` +- `resources/boost/skills/translations/SKILL.md` + +## Copy-Paste Prompt (Run Full Checklist) + +Use this when launching `FrontendImplementationAgent`: + +> Act as **FrontendImplementationAgent** for this Laravel project. +> Read and follow `DESIGN.md`, `AGENTS.md`, and the relevant skills in `resources/boost/skills/**/SKILL.md`. +> Run the **entire Frontend Criteria Checklist** end-to-end: +> 1. detect all changed/new UI surfaces and reusable frontend opportunities, +> 2. create/update missing Blade components, +> 3. enforce Tailwind CSS v4 and design-token usage, +> 4. enforce component reuse across all touched views, +> 5. verify accessibility and responsive states across mobile, tablet, and desktop, +> 6. run required execution gates, +> 7. return a final checklist report with pass/fail per item and remaining gaps. +> Do not stop early after partial success. + +## Frontend Criteria Checklist (Mandatory) + +### 1) Scope Detection + +- [ ] Identify all new/changed UI surfaces in the current change set (`resources/views/**`, component views, Livewire view files, and relevant frontend assets). +- [ ] Use a no-silent-skip rule: every touched UI file is listed in the final report, even if no visual changes were needed. +- [ ] Identify repeated UI fragments that should become reusable Blade components (candidate threshold: repeated in 2+ locations, or likely to repeat based on feature direction). +- [ ] Map each touched UI surface to either: + - [ ] dedicated reusable Blade component + - [ ] page-specific composition layer only (document why extraction is not yet justified) +- [ ] Confirm no changed surface is left without frontend and componentization review. + +### 2) Baseline Frontend Rules + +- [ ] Tailwind CSS **v4** conventions are applied throughout touched UI. +- [ ] Styling is utility-first in markup (avoid ad-hoc custom selector CSS for component styling). +- [ ] Frontend implementation is mobile-first with explicit responsive behavior (`sm:`, `md:`, `lg:`, etc.) where needed. +- [ ] Add responsive intent for each major touched surface (what changes across mobile, tablet, desktop and why). +- [ ] Maintain interaction parity across breakpoints; key actions should remain discoverable and operable at all target sizes. +- [ ] Dark mode variants are added where relevant for the feature context, or explicitly documented as intentionally not applicable. +- [ ] UI behavior is deterministic and state-focused (not just static appearance-focused). +- [ ] Do not remove existing reusable components without explicit approval. + +### 3) Component-First Coverage Matrix (Dedicated Component Required) + +Each touched UI type below must be reviewed for dedicated component extraction and reuse. + +#### Blade Components (`resources/views/components/**`) + +- [ ] Every repeated UI element is implemented as a Blade component. +- [ ] Semantic HTML is preserved during extraction (headings, lists, landmarks, buttons/links, form control semantics). +- [ ] Component API is consistent with `@props`, named slots, and `$attributes->merge([...])`. +- [ ] Variants and sizes are handled through component API (not duplicated markup blocks) using a consistent variant naming taxonomy. +- [ ] Components expose proper states (default/hover/focus/disabled/loading/error where relevant). + +#### Blade Page Views (`resources/views/**`) + +- [ ] Page views compose from components; they do not duplicate raw repeated element markup. +- [ ] Headings, buttons, inputs, badges, cards, alerts, and tables/lists use reusable components where possible. +- [ ] No repeated element pattern appears in multiple pages without component extraction. +- [ ] Tablet and desktop content density/readability is checked (line length, spacing rhythm, and visual hierarchy remain readable beyond mobile). + +#### Livewire UI Views (`resources/views/livewire/**` or project path) + +- [ ] Reused Livewire UI fragments are rendered via shared Blade components where possible. +- [ ] Livewire states (loading/dirty/error/empty) are represented with consistent reusable UI elements. +- [ ] No direct style drift between Blade-only and Livewire-driven surfaces for shared patterns. +- [ ] Shared interactions keep equivalent behavior across mobile/tablet/desktop (same state meaning, not necessarily identical layout). + +#### Styleguide and Component Discovery (`/styleguide`, `config/styleguide.php`) + +- [ ] Existing styleguide options were checked before creating new components. +- [ ] New reusable components are registered/discoverable where the project expects registration. +- [ ] Usage examples exist for non-trivial components or variants. + +### 4) Tailwind v4 Token and Styling Rules (Mandatory) + +- [ ] Use design tokens and `@theme` values before introducing one-off values. +- [ ] Hardcoded hex colors, arbitrary spacing/radius, and inline style overrides are avoided unless justified. +- [ ] If one-off values are used, document the reason and why existing tokens are insufficient. +- [ ] Repeated utility groups are extracted into components instead of copied between files. +- [ ] Class scanning/source coverage is correct for touched templates/paths. +- [ ] Tailwind setup remains compatible with latest v4 conventions in the project. + +### 5) Accessibility and UX States (Mandatory) + +- [ ] All interactive controls have visible `focus-visible` states. +- [ ] Touch targets for interactive controls follow minimum usable size (`min-h-[44px]` / `min-w-[44px]` where relevant). +- [ ] Icon-only controls provide `aria-label` or equivalent accessible name. +- [ ] Disabled, empty, loading, success, and error states are visually and semantically represented where applicable. +- [ ] Keyboard navigation flow is preserved for updated interactions. +- [ ] Orientation/viewport edge cases are reviewed for key interactions (mobile portrait/landscape, tablet portrait/landscape, desktop baseline widths). + +### 6) Reuse and Consistency Gates + +- [ ] Shared element patterns are implemented once and reused everywhere possible in the touched scope. +- [ ] Naming conventions for component files, props, and variants are consistent. +- [ ] No duplicate components exist for the same UI responsibility. +- [ ] Translation/localization usage stays consistent for user-facing copy in reusable components. +- [ ] Any acceptable exception to reuse/consistency is explicitly documented in the final report. + +### 7) Compatibility Guidance and Execution Gates + +Compatibility is treated as a required quality guideline. It is not a separate hard fail gate beyond the project build/lint requirements. + +- [ ] Frontend build passes (`npm run build` or project-equivalent build command). +- [ ] Relevant formatting/linting checks pass for touched frontend files. +- [ ] Manual responsive verification is completed and documented for mobile, tablet, and desktop breakpoints. +- [ ] Manual interaction verification is completed for focus/hover/disabled/loading/error states across target device classes. + +### 8) Final Report Format (Required) + +- [ ] Provide file-by-file and component-by-component frontend coverage summary. +- [ ] Provide checklist pass/fail status for every section above. +- [ ] Include evidence notes for key decisions (component extracted, component deferred, token exception, dark mode exception, compatibility notes). +- [ ] List exact remaining gaps (if any) and blocked reasons. +- [ ] If all items pass, explicitly state: `Full DESIGN.md checklist passed`. + +### 9) Challenged Top 20 Improvements (Reference Tracker) + +Use this section as a quick validation tracker to confirm all major improvements were applied to this checklist version. + +- [ ] 1. Explicit touched-surface inclusion rules are defined. +- [ ] 2. No-silent-skip reporting rule is enforced. +- [ ] 3. Component extraction threshold is documented. +- [ ] 4. Page-specific composition exceptions require rationale. +- [ ] 5. Variant naming taxonomy consistency is required. +- [ ] 6. Responsive intent is documented per major surface. +- [ ] 7. Mobile/tablet/desktop layout checks are explicitly required. +- [ ] 8. Orientation and viewport edge-case review is included. +- [ ] 9. Interaction parity across breakpoints is addressed. +- [ ] 10. Dark mode applicability and exceptions are explicit. +- [ ] 11. Semantic HTML requirement is included in extraction rules. +- [ ] 12. Icon-only accessible naming requirement is explicit. +- [ ] 13. Tablet/desktop readability and density checks are added. +- [ ] 14. Blade/Livewire state consistency is reinforced. +- [ ] 15. Token-first styling rule is explicit. +- [ ] 16. One-off style exception documentation is required. +- [ ] 17. Styleguide discovery and registration expectations are explicit. +- [ ] 18. Localization consistency checks are preserved and clarified. +- [ ] 19. Final report evidence expectations are strengthened. +- [ ] 20. Known acceptable exceptions must be documented. diff --git a/README.md b/README.md index 44540be..8ff0c5b 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,8 @@ Shared Laravel coding and architecture guidelines for codebar-ag projects, optim ## Requirements -- **PHP:** ^8.4 -- **Laravel:** 12.x (Illuminate 12 components) +- **PHP:** ^8.4 (8.4 and 8.5; SemVer caret includes any future 8.x before 9.0) +- **Laravel:** 12.x or 13.x (`illuminate/console` and `illuminate/support`: `^12.41.1|^13.0`) - **Laravel Boost:** ^2.2 (installed automatically as a dependency) --- @@ -270,7 +270,7 @@ If your editor supports MCP (Model Context Protocol), configure it to use the Bo ## Claude-based skills validation -This package validates its own skills using Pest and the [Laravel AI SDK](https://laravel.com/docs/12.x/ai-sdk): +This package validates its own skills using Pest and the [Laravel AI SDK](https://laravel.com/docs/12.x/ai-sdk) (see also the [13.x docs](https://laravel.com/docs/13.x/ai-sdk) when developing on Laravel 13): - **Run locally**: `vendor/bin/pest --group=skills` - **Environment**: Set `ANTHROPIC_API_KEY` and optionally `ANTHROPIC_MODEL` (default in `phpunit.xml.dist`: `claude-haiku-4-5`). diff --git a/TESTS.md b/TESTS.md new file mode 100644 index 0000000..bcb62c8 --- /dev/null +++ b/TESTS.md @@ -0,0 +1,276 @@ +# Test Criteria Checklist + +This file is an execution runbook for `TestAgent`. + +Goal: run the full testing checklist end-to-end and return objective PASS/FAIL evidence. + +## Agent and Skills + +- Primary role: `TestAgent` +- Supporting roles (only if needed): `BackendImplementationAgent`, `ReviewAgent` + +Load these skills first: + +- Core testing: `pesttesting`, `phpunit`, `phpstan` +- Quality and formatting: `php`, `general` +- Domain skills by touched files: `models`, `enums`, `jobs` + +Skill references: + +- `resources/boost/skills/pesttesting/SKILL.md` +- `resources/boost/skills/phpunit/SKILL.md` +- `resources/boost/skills/phpstan/SKILL.md` +- `resources/boost/skills/php/SKILL.md` +- `resources/boost/skills/general/SKILL.md` +- `resources/boost/skills/models/SKILL.md` +- `resources/boost/skills/enums/SKILL.md` +- `resources/boost/skills/jobs/SKILL.md` + +## Copy-Paste Launch Prompt + +Use this to launch `TestAgent`: + +> Act as **TestAgent** for this Laravel project. Read and follow `TESTS.md`, `AGENTS.md`, and relevant skills in `resources/boost/skills/**/SKILL.md`. Execute the entire checklist in deterministic order, produce required evidence for each section, and do not silently skip any step. If blocked, mark `BLOCKED` with reason and remediation. + +## Hard Pass/Fail Thresholds + +The run is `PASS` only if all of the following are true: + +- Test suite result: `0` failing tests. +- PHPStan result: `0` errors at **Level 9**. +- Pint result: `0` remaining formatting violations. +- Checklist result: no unresolved `FAIL` or `BLOCKED` items. + +## No Silent Skip Policy + +- Any step that cannot run must be marked `BLOCKED`. +- Every `BLOCKED` item must include: + - blocking reason + - impact + - exact next remediation step +- Never report `PASS` if any item is `BLOCKED`. + +## Deterministic Run Order + +Run steps in this exact order: + +1. Scope detection and class inventory. +2. Map classes to required test files. +3. Add/update missing tests by class type. +4. Run targeted tests for changed scope. +5. Run full test suite. +6. Run `vendor/bin/phpstan analyse` (Level 9). +7. Run `vendor/bin/pint`. +8. Produce final evidence report. + +## Canonical Commands + +- `php artisan test` +- `vendor/bin/phpstan analyse` +- `vendor/bin/pint` + +Optional while iterating: + +- `vendor/bin/pest` +- `vendor/bin/phpunit` + +## Test Naming Convention (Dedicated Test Class Required) + +Every touched class type requires a dedicated test file (no mega test files). + +- `App\Models\Invoice` -> `tests/Unit/Models/InvoiceTest.php` +- `App\Actions\ProcessInvoice` -> `tests/Unit/Actions/ProcessInvoiceTest.php` +- `App\Services\BillingService` -> `tests/Unit/Services/BillingServiceTest.php` +- `App\Http\Controllers\InvoiceController` -> `tests/Feature/Http/Controllers/InvoiceControllerTest.php` +- `App\Http\Middleware\EnsureTenant` -> `tests/Feature/Http/Middleware/EnsureTenantTest.php` +- `App\Livewire\Invoices\CreateInvoice` -> `tests/Feature/Livewire/Invoices/CreateInvoiceTest.php` + +## Coverage Dimensions (Minimum for Each Touched Class) + +For each touched class, include as applicable: + +- Happy path behavior +- Validation/guard path +- Failure/error path +- Authorization path +- Side effects and contract assertions + +## Mandatory Checklist + +### 1) Scope Detection + +- [ ] Identify all new/changed PHP classes in current change set. +- [ ] Map each class to test type (`Unit` or `Feature`). +- [ ] Confirm no changed class is left without dedicated test coverage. + +### 2) Baseline Rules + +- [ ] Every new/changed class has dedicated automated tests. +- [ ] Prefer Pest syntax for new tests unless area is intentionally PHPUnit class-based. +- [ ] Use deterministic test setup (factories/states over ad-hoc inserts). +- [ ] Do not remove tests without explicit approval. + +### 3) Coverage Matrix by Class Type + +#### Models (`app/Models/*`) + +- [ ] Dedicated model test file exists. +- [ ] CRUD covered (create/read/update/delete or soft delete). +- [ ] Casts/helpers asserted. +- [ ] Every relation tested for type and behavior. + +#### Enums (`app/Enums/*`) + +- [ ] Dedicated enum test file exists. +- [ ] All cases verified. +- [ ] `label()` and `color()` verified per case. +- [ ] Backward compatibility checked for persisted values. +- [ ] Model enum casting verified where used. + +#### Jobs (`app/Jobs/*`) + +- [ ] Dedicated job test file exists. +- [ ] Dispatch path tested. +- [ ] `handle()` delegation to Action/Service tested. +- [ ] Queue controls tested (`$tries`, `$backoff`, `$timeout`, `$queue`) where relevant. +- [ ] `failed()` behavior tested for critical jobs. + +#### Actions (`app/Actions/*`) + +- [ ] Dedicated action test file exists. +- [ ] Public contract (`execute` or equivalent) tested. +- [ ] Success/failure and side effects asserted. + +#### Commands (`app/Console/Commands/*`) + +- [ ] Dedicated command test file exists. +- [ ] Arguments/options matrix tested. +- [ ] Success/failure exit code assertions exist. +- [ ] Key console output assertions exist. + +#### DTOs (`app/Data`, `app/DTO`, or project DTO path) + +- [ ] Dedicated DTO test file exists. +- [ ] Construction/defaults/type invariants tested. +- [ ] Normalization/serialization round-trip tested. +- [ ] Invalid/edge input behavior tested where relevant. + +#### Livewire Components (`app/Livewire/*`) + +- [ ] Dedicated component test file exists. +- [ ] Render and interaction flow tested. +- [ ] Validation/authorization tested. +- [ ] Emitted events and persistence effects tested. + +#### Notifications (`app/Notifications/*`) + +- [ ] Dedicated notification test file exists. +- [ ] Channel routing tested (`mail`, `database`, `broadcast`, etc. as used). +- [ ] Payload/content contract tested. + +#### Observers (`app/Observers/*`) + +- [ ] Dedicated observer test file exists. +- [ ] Expected event-driven side effects tested. +- [ ] Explicit "no unintended side effects" assertion exists where relevant. + +#### Policies (`app/Policies/*`) + +- [ ] Dedicated policy test file exists. +- [ ] Method-by-method allow/deny matrix tested for relevant actor roles. + +#### Providers (`app/Providers/*`) + +- [ ] Dedicated provider test file exists. +- [ ] `register` bindings tested (binding/singleton resolution). +- [ ] `boot` behavior tested (macros/events/wiring where applicable). + +#### Services (`app/Services/*`) + +- [ ] Dedicated service test file exists. +- [ ] Public contract/orchestration tested. +- [ ] External dependencies are intentionally mocked/faked. +- [ ] Failure handling and side effects asserted. + +#### Traits (`app/Traits/*` or project trait path) + +- [ ] Dedicated trait test file exists. +- [ ] Trait tested via minimal fixture class. +- [ ] Method composition/collision behavior covered where relevant. + +#### Controllers (`app/Http/Controllers/*`) + +- [ ] Dedicated feature test file exists. +- [ ] Route/controller contract assertions cover status + payload shape. +- [ ] Validation/auth/authz/error paths covered. +- [ ] Side effects (DB/events/jobs/notifications) asserted where applicable. + +#### Middleware (`app/Http/Middleware/*`) + +- [ ] Dedicated middleware test file exists. +- [ ] Pass-through and blocked behavior covered. +- [ ] Matrix includes guest/authenticated/role/state combinations as relevant. +- [ ] Response effects asserted (redirect/status/headers/context). + +### 4) Views and States (Mandatory) + +Define and test all relevant states per changed view/component: + +- [ ] `empty` +- [ ] `partialData` +- [ ] `fullData` +- [ ] `loading` +- [ ] `error` +- [ ] `unauthorized` +- [ ] `forbidden` +- [ ] `disabled` +- [ ] `archived` + +Rules: + +- [ ] Every changed view/template is called by tests (directly or through endpoint/component). +- [ ] A state matrix is explicitly documented in tests/comments. +- [ ] At least one key visible/behavior assertion exists per covered state. + +### 5) Execution Gates + +- [ ] Targeted tests for changed scope pass. +- [ ] Full test suite passes (`php artisan test`). +- [ ] PHPStan Level 9 passes (`vendor/bin/phpstan analyse`). +- [ ] Pint passes (`vendor/bin/pint`). + +### 6) Required Evidence + +Attach concise evidence for each run: + +- [ ] Scope inventory (changed classes and mapped test files). +- [ ] Test results summary (targeted + full). +- [ ] PHPStan summary (Level 9, error count). +- [ ] Pint summary (violations/fixes). +- [ ] List of test files created or updated. + +### 7) Final Report Template (Required) + +Use this exact structure: + +```text +Scope +- + +Added/Updated Tests +- + +Checklist Status +- Section 1: PASS|FAIL|BLOCKED +- Section 2: PASS|FAIL|BLOCKED +- Section 3: PASS|FAIL|BLOCKED +- Section 4: PASS|FAIL|BLOCKED +- Section 5: PASS|FAIL|BLOCKED +- Section 6: PASS|FAIL|BLOCKED + +Blockers +- + +Final Verdict +- Full TESTS.md checklist passed +``` diff --git a/composer.json b/composer.json index 53e9d0b..027f691 100644 --- a/composer.json +++ b/composer.json @@ -10,8 +10,8 @@ ], "license": "MIT", "require": { - "illuminate/console": "^12.41.1", - "illuminate/support": "^12.41.1", + "illuminate/console": "^12.41.1|^13.0", + "illuminate/support": "^12.41.1|^13.0", "laravel/boost": "^2.2", "php": "^8.4" }, @@ -32,11 +32,11 @@ } }, "require-dev": { - "laravel/pint": "^1.27", - "phpunit/phpunit": "^11.0", "laravel/ai": "^0.2.0", - "orchestra/testbench": "^10.0", - "pestphp/pest": "^3.0", - "pestphp/pest-plugin-laravel": "^3.0" + "laravel/pint": "^1.27", + "orchestra/testbench": "^10.11|^11.0", + "pestphp/pest": "^4.4.1", + "pestphp/pest-plugin-laravel": "^4.1", + "phpunit/phpunit": "^12.5.12" } }