spark: aion

Author: sunchayn

.ai/agents/laravel-simplifier.md

@@ -0,0 +1,51 @@
+---
+name: laravel-simplifier
+description: Simplifies and refines PHP/Laravel code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
+model: opus
+---
+
+You are an expert PHP/Laravel code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying Laravel best practices and standards to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result of your years as an expert PHP developer.
+
+You will analyze recently modified code and apply refinements that:
+
+1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+
+2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:
+
+   - Use proper namespace declarations and organize imports logically
+   - Prefer explicit return type declarations on methods
+   - Follow Laravel conventions for controllers, models, and services
+   - Use proper error handling patterns (exceptions, custom exception classes)
+   - Maintain consistent naming conventions (PSR-12, Laravel standards)
+
+3. **Enhance Clarity**: Simplify code structure by:
+
+   - Reducing unnecessary complexity and nesting
+   - Eliminating redundant code and abstractions
+   - Improving readability through clear variable and function names
+   - Consolidating related logic
+   - Removing unnecessary comments that describe obvious code
+   - IMPORTANT: Avoid nested ternary operators - prefer match expressions, switch statements, or if/else chains for multiple conditions
+   - Choose clarity over brevity - explicit code is often better than overly compact code
+
+4. **Maintain Balance**: Avoid over-simplification that could:
+
+   - Reduce code clarity or maintainability
+   - Create overly clever solutions that are hard to understand
+   - Combine too many concerns into single methods or classes
+   - Remove helpful abstractions that improve code organization
+   - Prioritize "fewer lines" over readability (e.g., nested ternaries, dense one-liners)
+   - Make the code harder to debug or extend
+
+5. **Focus Scope**: Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.
+
+Your refinement process:
+
+1. Identify the recently modified code sections
+2. Analyze for opportunities to improve elegance and consistency
+3. Apply project-specific best practices and coding standards
+4. Ensure all functionality remains unchanged
+5. Verify the refined code is simpler and more maintainable
+6. Document only significant changes that affect understanding
+
+You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.

.ai/artifacts/.gitkeep

@@ -0,0 +1,63 @@
+## /reflect - Analyze session for retrospective on mistakes and patterns
+
+**Purpose**: Analyze the current session for reusable patterns and mistakes, then update modular guideline files (stubs or overrides) in `.ai/guidelines/` with learnings.
+
+**Usage**: `/reflect`
+
+**Process**:
+1. I will analyze the session for:
+    - Recurring mistakes that happened multiple times
+    - Universal patterns that are domain-agnostic
+    - Decision points where confusion arose
+    - Architectural/design patterns violated or followed
+    - Testing patterns and organization issues (AAA, Data Providers, etc.)
+    - Code quality and style issues (Commenting, PHP 8 features)
+    - Module boundary violations (Isolation, Contracts, Events)
+
+2. I will categorize learnings by their related guideline file:
+    - **Compliance/Process** → `.ai/guidelines/stubs/compliance.stub`
+    - **Modular Architecture** → `.ai/guidelines/stubs/architecture.stub`
+    - **PHP Standards** → `.ai/guidelines/php/core.blade.php` (override extending Boost PHP)
+    - **Laravel Architecture** → `.ai/guidelines/laravel/core.blade.php` (override extending Boost Laravel)
+    - **General Code Quality** → `.ai/guidelines/stubs/quality.stub`
+    - **PHPUnit Testing** → `.ai/guidelines/phpunit/core.blade.php` (override for PHPUnit standards)
+    - **Agent Behavior** → `.ai/guidelines/stubs/behavior.stub`
+
+3. I will determine if learnings should be:
+    - **Added to existing guidelines**: Universal, reusable patterns applicable to all future work
+    - **Saved as session notes**: Feature-specific or temporary learnings in `.ai/guidelines/stubs/session-learnings.stub` (create file if it doesn't exist)
+
+4. I will generate proposed changes with:
+    - Clear section title referencing the related guideline file
+    - Organized subsections matching existing modular structure
+    - Concrete examples using `<code-snippet>` tags where helpful
+    - Consistent formatting matching existing stubs (Zero Emoji Usage)
+    - Absolute file paths for all references
+
+5. I will show you the proposed changes and ask for confirmation
+
+6. Only after your approval will I:
+    - Update/Create the appropriate `.stub` or `.blade.php` files
+    - **MANDATORY**: Run `php artisan boost:update` to synchronize changes into `CLAUDE.md`
+
+**Confirmation prompt**:
+```
+Here are the proposed additions based on this session's learnings:
+
+[PROPOSED CHANGES TO .ai/guidelines/...]
+
+Do you want me to apply these changes and run boost:update? (yes/no)
+```
+
+**Guidelines for Updates**:
+- Follow the exact format of existing files (stubs or blade overrides)
+- Use standard Markdown headers and spacing
+- Add to existing sections when possible, create new sections only when necessary
+- Keep entries concise but complete with concrete examples
+- Mirror the style of existing guideline files (High density, professional tone)
+- Never add suggestions - only mandatory requirements
+- NEVER use emojis (including symbols like ✅/❌)
+- Use bold text for emphasis instead of icons
+- Ensure code examples use `<code-snippet>` tags
+
+**Note**: The command focuses on reusable patterns and mandatory requirements. After any modification to the modular files, `php artisan boost:update` must be executed to ensure the authoritative `CLAUDE.md` remains in sync with the source stubs and overrides.

.ai/commands/reflect.md

@@ -0,0 +1,29 @@
+# MANDATORY COMPLIANCE & STANDARDS
+
+**CRITICAL**: Every item in this file is a MANDATORY requirement. This document serves as the authoritative preamble for CLAUDE.md.
+
+---
+
+{!! Blade::render(file_get_contents(base_path('.ai/guidelines/stubs/compliance.stub')), ['assist' => $assist]) !!}
+
+---
+
+{!! Blade::render(file_get_contents(base_path('.ai/guidelines/stubs/architecture.stub')), ['assist' => $assist]) !!}
+
+---
+
+{!! Blade::render(file_get_contents(base_path('.ai/guidelines/stubs/quality.stub')), ['assist' => $assist]) !!}
+
+---
+
+{!! Blade::render(file_get_contents(base_path('.ai/guidelines/stubs/behavior.stub')), ['assist' => $assist]) !!}
+
+---
+
+@if(file_exists(base_path('.ai/guidelines/stubs/session-learnings.stub')))
+    {!! Blade::render(file_get_contents(base_path('.ai/guidelines/stubs/session-learnings.stub')), ['assist' => $assist]) !!}
+@endif
+
+---
+
+**Remember: Every single item in this document is a requirement, not a suggestion.**

.ai/guidelines/00-standards.blade.php

@@ -0,0 +1,11 @@
+{!! Blade::render(file_get_contents(base_path('vendor/laravel/boost/.ai/laravel/core.blade.php')), ['assist' => $assist]) !!}
+
+### Requests
+- Never use inline validation. Always use Form Requests.
+
+### Resources
+- **No database queries in API Resources.** Make sure the controller are providing all needed data.
+
+### Architecture Constraints
+- **Follow event-driven architecture** with service contracts and dependency injection.
+- **Actions & DTOs**: Follow strict structural requirements (defined in **Guidelines: Architecture**). For the creation procedure, refer to **Skill: create-dto-action**.

.ai/guidelines/laravel/core.blade.php

@@ -0,0 +1,80 @@
+{!! Blade::render(file_get_contents(base_path('vendor/laravel/boost/.ai/phpunit/core.blade.php')), ['assist' => $assist]) !!}
+
+### Suite Selection & Naming
+
+#### 1. Unit Tests (`*UnitTest.php`)
+- **Purpose**: Test a single class in isolation without Laravel's container or database.
+- **Base Class**: `Tests\Support\TestCases\UnitTestCase`.
+- **Location**: Mirror `app/` in `tests/App/` (e.g., `tests/App/Modules/Auth/DTOs/UserDataUnitTest.php`).
+- **Targets**: DTOs, Value Objects, Exceptions, pure logic classes.
+- **Preference**: Use whenever logic doesn't require database or complex service integration.
+
+#### 2. Functional Tests (`*FunctionalTest.php`)
+- **Purpose**: Test the integration of internal module components and business logic.
+- **Base Class**: `Tests\Support\TestCases\FunctionalTestCase`.
+- **Location**: Mirror `app/` in `tests/App/` (e.g., `tests/App/Modules/Auth/Actions/RegisterUserActionFunctionalTest.php`).
+- **Targets**: Actions (main entry points), Models (relationships/scopes), Service Providers.
+- **Entails**: Database access, Event fakes, mocking other module Actions.
+
+#### 3. Integration Tests (`*IntegrationTest.php`)
+- **Purpose**: Test the HTTP Transport layer and the full request/response cycle.
+- **Base Class**: `Tests\Support\TestCases\FunctionalTestCase`.
+- **Location**: Mirror `app/Http/` in `tests/Integration/Http/` (e.g., `tests/Integration/Http/Api/Auth/LoginIntegrationTest.php`).
+- **Targets**: Controllers, Form Requests, API Resources, Routing.
+- **Entails**: Mocking the business logic (Action) to focus strictly on the transport layer (validation, status codes, JSON structure).
+- **Mandatory**: Every Integration test MUST include a `test_it_integrates()` method that exercises the endpoint **without any mocking** to ensure the entire stack is correctly wired. This test does NOT need to be comprehensive; it should simply make a valid request and ensure it succeeds.
+
+#### Mirroring Rule
+- All tests in `tests/App/` and `tests/Integration/` MUST mirror the corresponding directory structure of the file being tested.
+
+### AAA+A Formatting
+*(Procedure: Refer to Skill: format-phpunit-tests)*
+- **Supported Blocks**: `// Arrange`, `// Anticipate` (for mocks/expectations), `// Act`, `// Assert`.
+- **Absolute Enclosure**: **NOTHING** must be defined outside of these blocks. Every piece of code MUST fall under one of these headers.
+- **Leave exactly ONE extra line break** after each comment (`// Arrange\n\n`).
+- **Never add extra content to the block comments**: Put the comment in a separate line, with a two line break apart from the block comment.
+<code-snippet name="Example clean AAA blocks" lang="php">
+    ❌ BAD
+    // Arrange - Create a user in the US region so it triggers a {particular} pre-condition
+
+    $user = User::region('us')->create();
+
+    ---
+
+    ✅ GOOD
+    // Arrange
+
+    // Create a user in the US region so it triggers a {particular} pre-condition
+    $user = User::region('us')->create();
+</code-snippet>
+
+### Dependency Injection
+- **Always use `resolve(ClassName::class)`** - Laravel IoC will inject spies/mocks automatically.
+- **Create spies before calling `resolve()`.**
+- **Never manually instantiate with `new ClassName()`** if it has dependencies. Unless it is a Unit test.
+
+### Data Providers
+- **Always use `Generator`**.
+- **Use descriptive string keys**.
+
+<code-snippet name="Data Provider Example" lang="php">
+    public static function dataProvider(): Generator
+    {
+        yield 'successful scenario' => [
+            'input' => 'valid',
+            'expected' => true,
+        ];
+
+        yield 'unsuccessful scenario' => [
+            'input' => 'invalid',
+            'expected' => false,
+        ];
+    }
+</code-snippet>
+
+### Implementation Standards
+- **Use `spy()` over `mock()`** unless you need to set expectations (Anticipate block).
+- **Always use `LogFake::bind()`** to mock logs.
+- **Never test private methods directly**.
+- **NEVER test controllers directly** (use HTTP endpoint integration tests).
+- **Always add `CoversClass(ClassName::class)` attirubte(s)** to all tests adding the classes being covered.

.ai/guidelines/phpunit/core.blade.php

@@ -0,0 +1,4 @@
+## Laravel Pint Code Formatter
+
+- You must run `composer style:fix` before finalizing changes to ensure your code matches the project's expected style.
+- Do not run `vendor/bin/pint --test`, simply run `composer style:fix` to fix any formatting issues.

.ai/guidelines/pint/core.blade.php

@@ -0,0 +1 @@
+session-learnings.stub

.ai/guidelines/stubs/.gitignore

@@ -0,0 +1,59 @@
+## MODULAR ARCHITECTURE
+
+### CORE ARCHITECTURAL PRINCIPLE
+The application is structured into **Modules** representing distinct business domains. Each module must be self-contained and isolated.
+
+### MODULE BOUNDARIES
+- **Modules must be isolated**. No direct use of another module's Models/Actions.
+- **Communication via Contracts**: Use interfaces in `app/Modules/Domain/Contracts`.
+- **Prefer Events for Decoupling**.
+- **No Cross-Module Database Joins**.
+
+### DIRECTORY STRUCTURE
+*(Procedure: Refer to Skill: 'scaffold-module')*
+
+- **Logic**: `app/Modules/{Domain}/`
+    - `Actions/`: Single-method business logic classes.
+    - `Models/`: Domain-specific Eloquent models.
+    - `DTOs/`: Readonly data transfer objects.
+    - `Contracts/`: Interfaces for cross-module interaction.
+    - `Enums/`: Domain enumerations.
+    - `Services/`: Complex logic spanning multiple actions.
+    - `Exceptions/`: Domain-specific exceptions.
+- **Transport**: `app/Http/{Application}/{Domain}/`
+    - `Controllers/`: Bridges HTTP requests to Actions.
+    - `Requests/`: Form Requests for validation.
+    - `Resources/`: Eloquent API Resources for JSON transformation.
+    - `Shared/`: Shared components for all domains.
+
+### SHARED COMPONENTS
+- **Definition**: Components located in `app/Modules/Shared/` (e.g., `User` model, shared interfaces).
+- **Status**: Shared models are considered **Global Contracts**. They may be used directly across module boundaries without additional interfaces.
+- **Limit**: Only truly universal domain concepts should reside in the Shared module.
+### SERVICES
+- **Purpose**: Orchestrate logic spanning multiple Actions or interact with complex external SDKs.
+- **Constraint**: Must adhere to strict typing and constructor property promotion.
+- **Caution**: Avoid "fat services" that violate single-responsibility. Prefer granular Actions.
+
+### EXCEPTIONS
+- **Standard**: Actions must throw domain-specific exceptions (e.g., `UnableToLoginException`) for expected failure states.
+- **Handling**: Controllers are responsible for catching domain exceptions and converting them to HTTP responses (e.g., via `ValidationException`).
+
+### ACTIONS
+*(Procedure: Refer to Skill: 'create-dto-action')*
+
+- **Naming**: Use `VerbNounAction` naming convention (e.g., `CreateUserAction`).
+- **Method**: Must have exactly **ONE** public method: `public function execute()`.
+- **Parameters**: Accept only **ONE** parameter (use a DTO for multiple).
+- **No Data Querying**: Actions should be pure executors of logic. They must NOT perform database queries (e.g. `User::find()`) to retrieve their inputs.
+- **Pure State**: All necessary models or state MUST be provided to the `execute()` method via the DTO.
+- **Isolation**: Return Contracts (e.g. `AuthenticatableWithIdentity`) rather than concrete Models.
+- **Testability**: Mark with `/** @final */` annotation instead of the `final` keyword.
+
+### DTOS
+*(Procedure: Refer to Skill: 'create-dto-action')*
+
+- **Structure**: Must be `final readonly` classes.
+- **Promotion**: Use PHP 8.2+ `readonly` class modifier and constructor property promotion.
+- **Provisioning**: DTOs are responsible for encapsulating ALL inputs required by the Action.
+- **Factories**: Use static factory methods (e.g., `fromRequest()`) to resolve and inject models/dependencies. The factory is the layer where "finding" data occurs, keeping the Action clean.

.ai/guidelines/stubs/architecture.stub

@@ -0,0 +1,39 @@
+## COMPOSER SCRIPTS
+
+This project defines named scripts in `composer.json`. **Always prefer `composer scripts` over calling vendor binaries directly** when a script exists for the tool. Check the scripts section of `composer.json` before invoking any quality tool.
+
+| Script | Purpose |
+|---|---|
+| `composer test` | Clear config + run full test suite |
+| `composer test:parallel` | Run tests in parallel via paratest |
+| `composer test:coverage` | Generate HTML coverage report |
+| `composer style:fix` | Run Laravel Pint formatter |
+| `composer phpstan` | Run PHPStan with project config + 2G memory limit |
+| `composer rector` | Run Rector with project config |
+
+---
+
+## AGENT BEHAVIOR
+
+### Communication Rules
+- **No Emojis** in responses (except requirement markers).
+- **No Fluff Documentation**: Never generate unnecessary markdown files (e.g., `COMPLETION_REPORT.md`, `SUMMARY.md`, etc.).
+- **Never assume action from observation**.
+- When the user asks a question about your changes, don't imply the user is asking you to change anything. **Answer the question** as is and wait for the next instruction.
+
+### Artifact Management Rules
+
+- **Use `.ai/artifacts/` folder EXCLUSIVELY** for all AI-generated artifacts including:
+  - Execution plans (unless you are in an environment that has interactive plans like Antigravity)
+  - Summaries
+  - Audits
+  - Analysis reports
+  - Investigation notes
+  - Any other AI-generated documentation
+- **NEVER write AI-generated artifacts** to other folders (e.g., `docs/`, root directory).
+- **Keep artifacts organized** with descriptive filenames including dates (e.g., `SECURITY_AUDIT_2026_01_14.md`).
+- **NEVER modify user-managed documentation** in `docs/`, `wiki/`, or any other project folders unless explicitly requested.
+
+### TASK FINALIZATION
+*(Refer to skill: `task-finalization` for procedure)*
+Before completing a task, you MUST run the project's quality tools (Style, Analysis, Refactor, Types, Tests) as defined in the skill. This is not optional.