@event4u/agent-config 1.9.1

package/.agent-src/skills/migration-creator/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: migration-creator
+description: "Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness."
+source: package
+---
+
+# migration-creator
+
+## When to use
+
+Use this skill when the user asks to create a database migration, add a column, create a table, or modify the schema.
+
+## Procedure: Create a migration
+
+1. **Read conventions** — Check `./agents/` and `AGENTS.md` for table prefixes, column naming, multi-tenant setup.
+2. **Generate migration** — `php artisan make:migration create_xyz_table` (or add_column, etc.).
+3. **Write schema** — Follow naming conventions, add indexes for WHERE/JOIN columns, use `decimal` for money.
+4. **Verify** — Run migration (`php artisan migrate`), then rollback (`php artisan migrate:rollback`) to confirm reversibility.
+
+## All projects
+
+- Use `decimal` for money — never `float`.
+- Add indexes for columns used in WHERE clauses and JOINs.
+- Match existing column naming patterns in the same table or domain.
+- Always include a reversible `down()` method.
+
+## Laravel projects
+
+### Multi-database architecture
+
+Some projects use multiple database connections. Check `config/database.php` for connections.
+
+| Check | How |
+|---|---|
+| Available connections | `config/database.php` → `'connections'` array |
+| Migration directories | `database/migrations/` (default), check for additional directories |
+| Custom migrate commands | `php artisan list migrate` — look for project-specific commands |
+
+**Always determine which database the table belongs to before creating a migration.**
+
+### API database migration
+
+```bash
+php artisan make:migration create_example_table
+```
+
+```php
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::connection('api_database')->create('example_table', function (Blueprint $table): void {
+            $table->id();
+            $table->unsignedBigInteger('customer_id');
+            $table->string('name');
+            $table->boolean('is_active')->default(true);
+            $table->timestamps();
+            $table->softDeletes();
+
+            $table->foreign('customer_id')
+                ->references('id')
+                ->on('customers')
+                ->onDelete('cascade');
+
+            $table->index('is_active');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::connection('api_database')->dropIfExists('example_table');
+    }
+};
+```
+
+### Customer database migration
+
+```bash
+php artisan make:migration:customer AddWeatherColumn --table=cl_lv_weather
+```
+
+Customer database tables use the `cl_` prefix (e.g. `cl_user`, `cl_lv_weather`).
+
+### Adding a column (with explicit connection)
+
+```php
+return new class extends Migration {
+    public function up(): void
+    {
+        Schema::connection('my_connection')->table('example', function (Blueprint $table): void {
+            $table->unsignedInteger('new_column')->after('existing_column');
+        });
+    }
+
+    public function down(): void
+    {
+        Schema::connection('my_connection')->table('example', function (Blueprint $table): void {
+            $table->dropColumn('new_column');
+        });
+    }
+};
+```
+
+### Running migrations
+
+```bash
+# Default connection
+php artisan migrate                           # development
+php artisan migrate --env=testing             # testing
+
+# Multi-tenant / custom — check AGENTS.md or module docs for project-specific commands
+# Example: php artisan migrate:tenants, php artisan migrate --database=tenant
+```
+
+## Composer / legacy projects
+
+- Check where existing migrations live (e.g. `core/migrations/`).
+- Use the existing migration format and naming conventions in the project.
+
+## Column conventions
+
+- Foreign keys: `{entity}_id` (e.g. `customer_id`, `user_id`)
+- Booleans: `is_` prefix (e.g. `is_active`, `is_default`)
+- Dates: descriptive suffix (e.g. `upload_date`, `deleted_at`)
+- Always use `unsignedBigInteger` for foreign keys referencing `id()` columns
+- Use `->after('column')` to place new columns logically
+
+## Output format
+
+1. Migration file with up() and down() methods
+2. Model updates if columns or relationships changed
+
+## Gotcha
+
+- Always check if the table/column already exists before creating the migration — the model doesn't always check.
+- Multi-tenant migrations need special handling — customer tables use different prefixes.
+- Don't modify existing migrations that have been deployed — create a new migration instead.
+- The model forgets `->after('column')` for column ordering — MariaDB respects it, and it matters for readability.
+
+## Do NOT
+
+- Do NOT create migrations without specifying the correct connection when multiple databases exist.
+- Do NOT create tables without checking the project's naming conventions (prefixes, casing).
+- Do NOT use raw SQL in migrations when Schema builder works.
+- Do NOT forget to make migrations reversible (down method).
+- Do NOT use `float` for money — use `decimal`.
+- Do NOT forget indexes on foreign keys and frequently filtered columns.
+
+## Adversarial review
+
+Before finalizing a migration, run the **`adversarial-review`** skill.
+Focus on the "Database migrations" attack questions: Can this destroy data? Is rollback possible?
+
+## Auto-trigger keywords
+
+- database migration
+- create migration
+- table prefix
+- column naming
+- add column
+- create table

package/.agent-src/skills/module-management/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: module-management
+description: "Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions."
+source: package
+---
+
+# module
+
+## When to use
+
+Use this skill when creating, exploring, or working within a module in `app/Modules/`.
+
+## Procedure: Work with modules
+
+1. Read `app/Modules/README.md` for the full module documentation.
+2. Check `app/Providers/ModuleServiceProvider.php` for auto-loading behavior.
+3. If module-level agent docs exist (`app/Modules/{Module}/agents/`), read them.
+
+## Detection
+
+Check if `app/Modules/` exists in the project. If it doesn't, the project doesn't use modules.
+
+## Architecture
+
+### ModuleServiceProvider
+
+`app/Providers/ModuleServiceProvider.php` auto-discovers modules by scanning `app/Modules/`:
+
+1. **Route loading** — automatically loads `Routes/api.php`, `Routes/web.php`, `Routes/console.php`
+   - API routes: prefixed with `/api`, `api` middleware
+   - Web routes: `web` middleware
+   - Console routes: loaded via `require_once`
+   - Fallback: also checks lowercase `routes/` for legacy modules
+2. **Command registration** — auto-discovers commands in `App/Console/Commands/`
+   - Fallback: also checks `Console/Commands/` for legacy modules
+
+### Module structure
+
+```
+app/Modules/{ModuleName}/
+├── App/                         # All application code (PSR-4)
+│   ├── Console/Commands/        # Artisan commands (auto-registered)
+│   ├── Enums/
+│   ├── Http/
+│   │   ├── Controllers/
+│   │   ├── Middleware/
+│   │   └── Requests/
+│   ├── Jobs/
+│   ├── Models/
+│   ├── Rules/
+│   └── Services/
+├── Routes/                      # Auto-loaded route files
+│   ├── api.php
+│   ├── web.php
+│   └── console.php
+├── Tests/                       # Module-specific tests
+│   ├── Component/
+│   ├── Integration/
+│   └── Unit/
+├── Docs/                        # Optional technical docs
+├── agents/                      # Agent docs for this module
+│   ├── features/
+│   ├── roadmaps/
+│   └── contexts/
+└── README.md                    # Optional module description
+```
+
+**Important:** Directory names use capital letters (App, Routes, Tests) for PSR-4 compliance.
+
+### Namespace convention
+
+```
+App\Modules\{ModuleName}\App\{Layer}\{Class}
+```
+
+Examples:
+- `App\Modules\ClientSoftware\App\Services\ImportService`
+- `App\Modules\ClientSoftware\App\Http\Controllers\Import\ImportDataController`
+- `App\Modules\ClientSoftware\App\Console\Commands\ProcessImportUploadsCommand`
+
+### Route conventions
+
+```php
+// Routes/api.php — auto-prefixed with /api by ModuleServiceProvider
+Route::name('v1.')
+    ->prefix('v1/{module-prefix}')
+    ->group(function(): void {
+        Route::get('/', [Controller::class, 'index'])->name('{module-prefix}.index');
+    });
+```
+
+- Route prefix: **kebab-case** (e.g., `client-software`, `grafana`)
+- Route names: **dot notation** (e.g., `v1.imports.index`)
+- Module name: **PascalCase** (e.g., `ClientSoftware`, `Grafana`)
+
+## Existing modules
+
+| Module | Purpose |
+|---|---|
+| `ApiClient` | External API client utilities |
+| `Backoff` | Retry/backoff logic |
+| `ClientSoftware` | Client software imports, uploads, processing |
+| `Grafana` | Grafana/Loki dashboard integration |
+| `Stubbing` | Test stubs and mocks |
+
+## Template
+
+The `.module-template` directory provides a scaffold for new modules:
+- `app/Modules/.module-template/` — copy and rename to create a new module
+- Contains placeholder route files, README, and directory structure
+- Replace `[MODULE_NAME]` and `[module-prefix]` placeholders
+
+## Agent docs in modules
+
+Modules can have their own agent documentation:
+
+```
+app/Modules/{Module}/agents/
+├── features/       # Module-scoped feature plans
+├── roadmaps/       # Module-scoped roadmaps
+└── contexts/       # Module-scoped context documents
+```
+
+## Output format
+
+1. Module directory structure following template conventions
+2. ServiceProvider, routes, and agent docs scaffolded
+
+## Auto-trigger keywords
+
+- Laravel module
+- module structure
+- module creation
+- module namespace
+
+### Validate
+
+- Verify namespace follows `App\Modules\{Name}\App\{Layer}` pattern.
+- Confirm `ModuleServiceProvider` auto-discovers the new module's routes and providers.
+- Run PHPStan on the module — must pass.
+- Run module tests — must pass.
+
+## Gotcha
+
+- Module namespace is `App\Modules\{Name}\App\{Layer}` — don't forget the extra `App` segment.
+- Routes in modules auto-register via `ModuleServiceProvider` — don't register them manually.
+- Don't put shared code in a module — shared code belongs in `app/` not `app/Modules/`.
+
+## Do NOT
+
+- Do NOT manually register module routes — `ModuleServiceProvider` handles this.
+- Do NOT use lowercase directory names (`routes/`, `app/`) — use `Routes/`, `App/`.
+- Do NOT put business logic in controllers — use module services.
+- Do NOT create a module for trivial functionality — only when logical separation is needed.

package/.agent-src/skills/multi-tenancy/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: multi-tenancy
+description: "Use when working with the multi-tenant architecture — customer DB switching, FQDN routing, tenant isolation, or cross-tenant operations."
+source: package
+---
+
+# multi-tenancy
+
+## When to use
+
+Use this skill when working with tenant-specific data, customer database connections, or any code that touches the dual-database architecture.
+
+
+Do NOT use when:
+- Single-database applications
+- Frontend-only changes
+
+## Procedure: Work with multi-tenancy
+
+1. **Gather context** — read `agents/docs/` for multi-tenant architecture, `config/database.php` for connection definitions, and search for the tenant switching service.
+2. **Identify connection** — determine whether the code touches central, tenant, or both databases. Set `$connection` explicitly on any new model.
+3. **Implement** — write the feature using the correct connection. Use the tenant switching service for cross-tenant operations. Never mix connections in a single query.
+4. **Verify isolation** — inspect the code for tenant leaks: global scopes, missing `$connection`, shared caches, or job serialization without tenant context.
+5. **Test** — write a test that exercises the tenant boundary: seed tenant-specific data, switch context, verify correct data is returned and other tenants' data is invisible.
+
+## Architecture overview
+
+```
+Request → Identify Tenant (JWT / subdomain / API key)
+        → Lookup credentials from central database
+        → Reconfigure tenant connection at runtime
+        → All tenant queries use tenant connection
+```
+
+### Dual-database pattern
+
+| Connection type | Purpose | Scope |
+|---|---|---|
+| Central / shared | Global data — tenants, config, shared resources | Shared across all tenants |
+| Tenant / customer | Tenant-specific data — domain entities | One per tenant |
+
+The central connection is typically the **default connection**.
+The tenant connection starts **empty** and is configured dynamically per request.
+
+### Additional connections
+
+Projects may have additional connections for admin operations, provisioning, or monitoring. Check `config/database.php`.
+
+## Core tenant switching service
+
+Search the codebase for the service responsible for tenant switching. Typical responsibilities:
+
+1. Store tenant context (e.g., in Laravel Context or a singleton)
+2. Load tenant configuration
+3. Set monitoring context (tenant ID, name, domain)
+4. Reconfigure the database connection with tenant credentials
+5. Bind tenant-specific services via the container
+
+## Model conventions
+
+### Setting `$connection`
+
+Every model **must** explicitly set its connection:
+
+```php
+// Central models
+class Tenant extends Model
+{
+    protected $connection = 'central_database';
+}
+
+// Tenant models
+class Project extends Model
+{
+    protected $connection = 'tenant_database';
+}
+```
+
+Check the project for the actual connection names and namespace conventions.
+
+## Tenant isolation rules
+
+- **Never query the tenant connection before the tenant is set.**
+- **Never mix connections in a single query** — use explicit joins or separate queries.
+- **Always specify `$connection`** on new models — never rely on the default.
+- **Use transactions per connection** — `DB::connection('tenant_database')->transaction(...)`.
+- **Artisan commands** that need tenant access must use the appropriate trait (search for it in the project).
+
+## Testing with tenants
+
+- Tests use dedicated tenant seeders (check `agents/docs/` for seeder conventions).
+- The testing database may consolidate multiple connections into a single DB for simplicity.
+- Use `RefreshDatabase` or manual seeding — never assume a specific tenant state from previous tests.
+
+## Common pitfalls
+
+| Problem | Solution |
+|---|---|
+| Query on `customer_database` returns empty | Customer not set yet — check middleware order |
+| Race condition in parallel tests | Each test process gets its own DB (parallel testing with separate DBs) |
+| Wrong tenant data in background jobs | Serialize customer ID, re-resolve in job's `handle()` method |
+| Migration on wrong connection | Specify `--database=customer_database` or set `$connection` in migration |
+
+
+## Output format
+
+1. Tenant-aware code with correct DB connection switching
+2. Verification that tenant isolation is maintained
+
+## Auto-trigger keywords
+
+- multi-tenant
+- tenant isolation
+- customer database
+- FQDN routing
+
+## Gotcha
+
+- Always verify which database connection is active before running queries — cross-tenant data leaks are critical bugs.
+- The model forgets to switch back to the main connection after tenant operations.
+- Queue jobs serialize the connection state — ensure the tenant context is restored when the job runs.
+- Don't use `DB::connection()` directly — use the tenant switching helpers.
+
+## Do NOT
+
+- Do NOT hardcode database names — always use connection names.
+- Do NOT assume `customer_database` is available in service providers or early boot.
+- Do NOT access tenant data in global middleware that runs before customer identification.
+- Do NOT store tenant DB credentials in code — they come from the `customer_databases` table.

package/.agent-src/skills/openapi/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: openapi
+description: "Use when documenting APIs — OpenAPI/Swagger, PHP attributes, Redocly validation, versioned specs — even when the user just says 'document this endpoint' without naming OpenAPI."
+source: package
+---
+
+# openapi
+
+## When to use
+
+Use this skill when adding or updating API documentation, writing OpenAPI annotations on controllers, or validating API specs.
+
+## Procedure: Add OpenAPI documentation
+
+1. **Gather context** — read `agents/docs/controller.md` for OpenAPI patterns, `agents/contexts/api-versioning.md` for versioning, and check 2-3 existing controllers for annotation style.
+2. **Detect tooling** — check `composer.json` for `l5-swagger` or `laravel-openapi`, look for `@OA\` vs `#[OA\` syntax in existing controllers, find the config file.
+3. **Write annotations** — add `#[OA\...]` attributes to the controller method. Include path, summary, tags, all parameters, and all response codes (200, 401, 403, 404, 422).
+4. **Define schemas** — create or reuse `#[OA\Schema]` for request/response types. Use `$ref` for shared types.
+5. **Validate** — run the spec validation (`npx @redocly/cli lint` or `php artisan l5-swagger:generate`). Fix any errors.
+6. **Verify accuracy** — compare the documented request/response with the actual controller + FormRequest + Resource to ensure they match.
+
+## OpenAPI attributes
+
+### Detection
+
+Check the project for OpenAPI tooling:
+- Look for `darkaonline/l5-swagger` or `vyuldashev/laravel-openapi` in `composer.json`.
+- Check for `@OA\` or `#[OA\` annotations in controllers.
+- Look for `config/l5-swagger.php` or similar config files.
+
+### PHP 8 attribute syntax
+
+Modern Laravel projects use PHP 8 attributes instead of docblock annotations:
+
+```php
+#[OA\Get(
+    path: '/projects',
+    summary: 'List all projects',
+    tags: ['Projects'],
+    parameters: [
+        new OA\Parameter(
+            name: 'page',
+            in: 'query',
+            required: false,
+            schema: new OA\Schema(type: 'integer'),
+        ),
+    ],
+    responses: [
+        new OA\Response(
+            response: 200,
+            description: 'Successful operation',
+        ),
+    ],
+)]
+public function __invoke(ListProjectsRequest $request): ProjectCollection
+{
+    // ...
+}
+```
+
+### Conventions
+
+- Place OpenAPI attributes **directly on the controller method**.
+- **Paths are relative to the server URL.** If the server is configured as `http://host/api/v1`,
+  then `path: '/projects'` resolves to `/api/v1/projects`. Never repeat the server prefix in the path.
+- Use **tags** matching the resource name (e.g., `Projects`, `Users`).
+- Document **all parameters** — path, query, and header.
+- Document **all response codes** — 200, 201, 401, 403, 404, 422.
+- Use **schema references** (`$ref`) for reusable types.
+
+## Response documentation
+
+### Resource schemas
+
+Define reusable schemas for API Resources:
+
+```php
+#[OA\Schema(
+    schema: 'Project',
+    properties: [
+        new OA\Property(property: 'id', type: 'integer'),
+        new OA\Property(property: 'name', type: 'string'),
+        new OA\Property(property: 'status', type: 'string', enum: ['active', 'archived']),
+    ],
+)]
+```
+
+### Pagination schema
+
+Document paginated responses with `meta` and `links`:
+
+```php
+#[OA\Response(
+    response: 200,
+    description: 'Paginated list',
+    content: new OA\JsonContent(
+        properties: [
+            new OA\Property(property: 'data', type: 'array', items: new OA\Items(ref: '#/components/schemas/Project')),
+            new OA\Property(property: 'meta', ref: '#/components/schemas/PaginationMeta'),
+        ],
+    ),
+)]
+```
+
+## Validation with Redocly
+
+If the project uses Redocly for OpenAPI validation:
+
+```bash
+# Validate the spec
+npx @redocly/cli lint openapi.yaml
+
+# Preview documentation
+npx @redocly/cli preview-docs openapi.yaml
+```
+
+Check for `.redocly.yaml` or `redocly.yaml` config in the project root.
+
+## Versioned documentation
+
+When the API uses URL-based versioning (e.g., `/api/v1/`, `/api/v2/`):
+
+- The version prefix is typically part of the **server URL**, not the individual endpoint paths.
+- Check the OpenAPI server configuration to understand what prefix is already included.
+- When creating a v2 endpoint, add new documentation — don't modify v1 docs.
+- Mark deprecated endpoints with `deprecated: true`.
+
+
+## Output format
+
+1. OpenAPI annotations as PHP attributes on controllers/models
+2. Spec validation passing via Redocly
+
+## Auto-trigger keywords
+
+- OpenAPI
+- Swagger
+- API documentation
+- PHP attributes
+- Redocly
+
+## Gotcha
+
+- OpenAPI attributes must match the actual endpoint behavior — stale docs are worse than no docs.
+- The model tends to define response schemas that don't match the Resource class output.
+- Don't document internal endpoints in the public API spec.
+
+## Do NOT
+
+- Do NOT skip OpenAPI documentation when creating new endpoints.
+- Do NOT document internal/private endpoints that are not part of the public API.
+- Do NOT use docblock `@OA\` annotations when the project uses PHP 8 attributes.
+- Do NOT hardcode example values that contain real customer data.
+- Do NOT create documentation that contradicts the actual implementation.