@event4u/agent-config 1.9.1

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

@@ -0,0 +1,217 @@
+---
+name: terragrunt
+description: "Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt."
+source: package
+---
+
+# terragrunt
+
+## When to use
+
+Use this skill when working with Terragrunt configurations (`.hcl` files), managing environment-specific settings, or orchestrating multi-module deployments.
+
+## Procedure: Write Terragrunt config
+
+1. Read the `root.hcl` in the target environment (`environments/pro/root.hcl` or `environments/sta/root.hcl`).
+2. Check existing `terragrunt.hcl` files in sibling directories for patterns.
+3. Read the target module's `variables.tf` to understand required inputs.
+
+## Project structure
+
+```
+environments/
+├── pro/
+│   ├── root.hcl                        # Root config (backend, providers)
+│   ├── core/
+│   │   ├── terragrunt.hcl              # Core module config
+│   │   └── {service}.yaml               # Module-specific variables
+│   ├── {service}/
+│   │   ├── terragrunt.hcl              # Service module config
+│   │   └── {service}.yaml              # Service-specific variables
+│   └── ...
+└── sta/
+    ├── root.hcl
+    └── ...
+```
+
+## Root configuration (`root.hcl`)
+
+The root HCL defines shared settings for all modules in an environment:
+
+### Environment variables
+
+```hcl
+locals {
+  env_files = merge(
+    yamldecode(file(".env.yaml")),           # Base env vars
+    try(yamldecode(file(".env.local.yaml")), {})  # Local overrides
+  )
+  env = { for k, v in local.env_files : k => get_env(k, v) }
+}
+```
+
+- `.env.yaml` — committed, shared environment config
+- `.env.local.yaml` — gitignored, local overrides (AWS profiles, etc.)
+- Real environment variables take precedence over file values.
+
+### Remote state
+
+```hcl
+remote_state {
+  backend = "s3"
+  config = {
+    bucket         = "${local.env.aws_account_name}-terraform-remote-state"
+    key            = "${path_relative_to_include()}/terraform.tfstate"
+    dynamodb_table = "${local.env.aws_account_name}-terraform-remote-state"
+    profile        = local.env.aws_profile
+    region         = local.env.aws_region
+    encrypt        = true
+  }
+}
+```
+
+### Provider generation
+
+Providers are auto-generated by Terragrunt (not manually written):
+
+```hcl
+generate "provider" {
+  path      = "provider-aws.tf"
+  if_exists = "overwrite_terragrunt"
+  contents  = <<EOF
+provider "aws" {
+  allowed_account_ids = ["${local.env.aws_account_id}"]
+  profile             = "${local.env.aws_profile}"
+  region              = "${local.env.aws_region}"
+}
+EOF
+}
+```
+
+### Terraform binary
+
+```hcl
+terraform_binary = "terraform"  # Explicitly NOT OpenTofu
+```
+
+## Module configuration (`terragrunt.hcl`)
+
+Each module directory contains a `terragrunt.hcl` that:
+
+1. **Loads module-specific variables** from a YAML file
+2. **Includes the root config** for backend and providers
+3. **Points to the Terraform module source**
+4. **Declares dependencies** on other modules
+5. **Passes inputs** by merging dependency outputs with local variables
+
+### Example pattern
+
+```hcl
+locals {
+  project = yamldecode(file("{service}.yaml"))
+}
+
+include {
+  path   = find_in_parent_folders("root.hcl")
+  expose = true
+}
+
+terraform {
+  source = "../../..//modules/{service}"
+}
+
+dependency "core" {
+  config_path = "../core"
+}
+
+inputs = merge(
+  dependency.core.outputs,
+  local.project
+)
+```
+
+## Conventions
+
+### Variable files
+
+- Use **YAML files** (not HCL) for module-specific variables.
+- Name them after the module (e.g., `my-service.yaml`).
+- Keep them in the same directory as `terragrunt.hcl`.
+
+### Dependencies
+
+- Use `dependency` blocks to reference other modules.
+- Core module outputs (VPC, DNS zones, etc.) are passed via `dependency.core.outputs`.
+- Merge dependency outputs with local variables in `inputs`.
+
+### Additional providers
+
+Some modules need extra providers (e.g., New Relic). Generate them in the module's `terragrunt.hcl`:
+
+```hcl
+generate "provider_newrelic" {
+  path      = "provider-newrelic.tf"
+  if_exists = "overwrite_terragrunt"
+  contents  = <<EOF
+provider "newrelic" {
+  account_id = "${include.locals.env.newrelic_account_id}"
+  api_key    = "${get_env("TF_VAR_newrelic_api_key", include.locals.env.newrelic_api_key)}"
+}
+EOF
+}
+```
+
+## Development tools
+
+The project uses **devbox** for tool management:
+
+```json
+{
+  "packages": ["terragrunt", "awscli2", "terraform@latest"]
+}
+```
+
+### Taskfile commands
+
+```bash
+task versions          # Show awscli, Terraform, Terragrunt versions
+task check:awscli      # Verify AWS CLI is configured
+task cache:clear       # Clear .terraform and .terragrunt-cache dirs
+```
+
+### Quick commands (devbox scripts)
+
+```bash
+devbox run i           # terragrunt init
+devbox run p           # terragrunt plan
+devbox run a           # terragrunt apply
+devbox run d           # terragrunt destroy
+```
+
+
+## Output format
+
+1. Terragrunt HCL files with DRY environment configuration
+2. Dependency graph and remote state references
+
+## Auto-trigger keywords
+
+- Terragrunt
+- multi-environment
+- DRY config
+- remote state
+
+## Gotcha
+
+- Terragrunt `dependency` blocks create implicit ordering — circular dependencies cause cryptic errors.
+- Don't duplicate Terraform variables in terragrunt.hcl — use `inputs` to pass them through.
+- The model tends to hardcode values that should come from `include` blocks — use DRY patterns.
+
+## Do NOT
+
+- Do NOT switch to OpenTofu — the project explicitly uses `terraform_binary = "terraform"`.
+- Do NOT hardcode AWS credentials — use AWS profiles from `.env.yaml`.
+- Do NOT commit `.env.local.yaml` — it contains local AWS profile overrides.
+- Do NOT modify `root.hcl` without understanding the impact on all modules.
+- Do NOT remove `dependency` blocks — they ensure correct apply order.
+- Do NOT use `terraform` commands directly — always use `terragrunt` as the wrapper.

package/.agent-src/skills/test-driven-development/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: test-driven-development
+description: "Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'."
+source: package
+---
+
+# test-driven-development
+
+## When to use
+
+* Adding a new function, method, or behavior
+* Fixing a bug (bug needs a regression test before the fix)
+* Refactoring a unit whose current behavior is unclear
+* Any task where expected behavior can be expressed as an assertion
+
+Do NOT use when:
+
+* Throwaway prototype or spike code explicitly marked as exploration
+* Boilerplate generation (migrations, config, scaffolding)
+* Pure documentation (`.md`, `AGENTS.md`, README)
+* Working inside this `agent-config` package on skill/rule markdown
+
+## Goal
+
+* Drive implementation from a verified-failing test, not the agent's
+  belief that code "should work".
+* Catch edge cases **before** production bugs.
+* Leave every change with a regression test running in CI.
+
+## The core discipline
+
+```
+1. Write ONE failing test that describes the desired behavior.
+2. Run it. WATCH it fail for the right reason.
+3. Write the MINIMUM production code to make it pass.
+4. Run it again. Watch it pass.
+5. Clean up (rename, deduplicate) while keeping the test green.
+```
+
+If step 2 is skipped, the test is not trusted — a test that has never
+failed proves nothing.
+
+## Procedure
+
+### 1. Identify the behavior to test
+
+State in one sentence: *"When X happens, the system should do Y."*
+
+Cannot state in one sentence? Scope too big — split into multiple tests,
+one sentence each.
+
+### 2. Write the failing test first
+
+Smallest test expressing step-1 sentence.
+
+* One assertion per behavior (multiple assertions OK only when describing
+  the same single behavior).
+* Real code paths, not mocks — mock only at I/O boundaries (HTTP, DB, time).
+* Descriptive name: `it_rejects_empty_email`, not `test_email_1`.
+
+### 3. Run the test and watch it fail
+
+Execute the single test (targeted, not full suite):
+
+```bash
+# PHP/Pest
+./vendor/bin/pest --filter=it_rejects_empty_email
+
+# JS/Vitest
+npx vitest run --testNamePattern "rejects empty email"
+```
+
+Required observations **before proceeding**:
+
+* Test **fails** (not errors).
+* Failure message matches expectation (missing behavior, not typo).
+* Passes immediately → it does not test what you think. Fix the test,
+  do not start writing production code.
+
+### 4. Write minimum code to pass
+
+**Just enough** production code to make the test green. No extra
+features, no unrelated refactoring, no "while I'm here" cleanups.
+
+Urge to add a parameter, edge case, or helper not covered by current
+test → stop. Belongs in the next RED step, not this GREEN step.
+
+### 5. Run again and watch it pass
+
+Re-run the same targeted command. Required:
+
+* New test passes.
+* No previously green tests turned red.
+* Output clean (no new warnings, deprecations, or noise).
+
+### 6. Refactor (only if green)
+
+With all tests green, you may:
+
+* Rename variables, methods, files
+* Extract duplication into helpers
+* Tighten types
+
+Do **not** add new behavior during refactor — needs its own failing test
+first. Re-run tests after refactor to confirm still-green.
+
+### 7. Repeat for the next behavior
+
+Back to step 1 with the next single-sentence behavior.
+
+## Output format
+
+1. Failing test (file + test name) with captured failure output
+2. Minimum-code diff that makes it pass
+3. Captured green-run output
+4. Refactor diff (optional)
+
+## Anti-rationalizations table
+
+The urge to skip TDD is strongest when TDD matters most. Name the
+rationalization and reject it:
+
+| Thought | Reality |
+|---|---|
+| "Too simple to need a test" | Simple code still breaks. A test costs less than one debug cycle. |
+| "I'll add the test after the code works" | A test written after code passes on first run — never failed. Proves nothing. |
+| "I already ran it manually" | Manual runs not repeatable. Next edit breaks it silently. |
+| "Deleting code I just wrote is wasteful" | Sunk cost. Cheap path: delete, write test, reimplement minimally. |
+| "I'll keep the code as reference while I write the test" | You will adapt it. That is test-after-the-fact with extra steps. Delete it. |
+| "I just need to explore the API first" | Spike on a throwaway branch. Then delete and restart with TDD. |
+| "The test is too hard to write" | Signals a design problem in the code, not the test. Listen. |
+| "This bug is urgent, no time for a test" | The test **is** the fastest path to a verified fix. Guessing takes longer. |
+
+
+## Examples
+
+### PHP / Pest
+
+```php
+// tests/Unit/EmailValidatorTest.php — RED
+it('rejects empty email', function () {
+    $result = (new EmailValidator())->validate('');
+    expect($result->isValid())->toBeFalse();
+    expect($result->error())->toBe('Email required');
+});
+```
+
+Run: `./vendor/bin/pest --filter='rejects empty email'` → fails
+(EmailValidator does not exist yet, or returns isValid()=true).
+
+```php
+// app/Validators/EmailValidator.php — GREEN (minimum)
+final class EmailValidator
+{
+    public function validate(string $email): EmailResult
+    {
+        if (trim($email) === '') {
+            return EmailResult::invalid('Email required');
+        }
+        return EmailResult::valid();
+    }
+}
+```
+
+Run filter again → passes. No additional rules (format, MX, length)
+until a next failing test drives them.
+
+### JS / Vitest
+
+```ts
+// src/retry.test.ts — RED
+import { retry } from './retry';
+
+it('retries a failing operation up to 3 times', async () => {
+  let attempts = 0;
+  const op = async () => {
+    attempts += 1;
+    if (attempts < 3) throw new Error('transient');
+    return 'ok';
+  };
+  await expect(retry(op)).resolves.toBe('ok');
+  expect(attempts).toBe(3);
+});
+```
+
+Run: `npx vitest run --testNamePattern "retries a failing"` → fails
+(`retry` undefined).
+
+```ts
+// src/retry.ts — GREEN (minimum)
+export async function retry<T>(op: () => Promise<T>): Promise<T> {
+  let lastError: unknown;
+  for (let i = 0; i < 3; i += 1) {
+    try { return await op(); } catch (e) { lastError = e; }
+  }
+  throw lastError;
+}
+```
+
+Run again → passes. Configurable attempt count, backoff, jitter all
+wait for their own failing tests.
+
+## Gotchas
+
+* Running the full suite instead of a filtered test hides the RED→GREEN
+  signal in noise. Always target first.
+* A test that passes on the very first run is not TDD — written against
+  existing code.
+* `expect()` with three or four assertions on unrelated fields describes
+  multiple behaviors. Split them.
+* Snapshot tests invert the discipline — they generate the expected
+  value from the code. Only use where human-readable output is the
+  contract (CLI, SQL strings).
+* Mocking the thing under test (instead of its I/O) tests the mock.
+
+## Do NOT
+
+* Do NOT write or modify production code before the failing test exists
+  and has been observed to fail
+* Do NOT accept a test that never failed as evidence the code works
+* Do NOT bundle refactors into the GREEN step
+* Do NOT silence a flaky test — diagnose or delete it
+* Do NOT skip the targeted RED-run because "I know it fails"
+
+## Anti-patterns
+
+* `it('works')` — no behavior described
+* One test covering "and/and/and" — split per behavior
+* Test reaching into private state instead of observable behavior
+* Test duplicating the production code's algorithm (tautology)
+
+## When to hand over to another skill
+
+* Quality tools, PHPStan, ECS, Rector → [`quality-tools`](../quality-tools/SKILL.md)
+* Full Pest conventions, Laravel testing helpers → [`pest-testing`](../pest-testing/SKILL.md)
+* Running tests inside Docker → [`tests-execute`](../tests-execute/SKILL.md)
+* Investigating why a test fails for non-obvious reasons →
+  [`systematic-debugging`](../systematic-debugging/SKILL.md)
+
+## Validation checklist
+
+Before marking TDD work complete:
+
+* [ ] Every new behavior has a test
+* [ ] Each test was observed to fail first, with a matching failure message
+* [ ] Minimum code was written to turn each RED into GREEN
+* [ ] All targeted tests pass
+* [ ] No adjacent test turned red
+* [ ] Output clean (no new warnings or deprecations)
+
+See also [`developer-like-execution`](../developer-like-execution/SKILL.md)
+for the broader think → analyze → verify loop this skill plugs into.

package/.agent-src/skills/test-performance/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: test-performance
+description: "Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives."
+source: package
+---
+
+# test-performance
+
+## When to use
+
+Use this skill when:
+
+- Tests are running too slowly (locally or in CI)
+- Database setup/teardown is a bottleneck
+- Parallel testing needs optimization
+- Seeders need performance analysis
+- CI pipeline test jobs need to be faster
+- Investigating flaky tests caused by database state
+
+## Procedure: Analyze test performance
+
+### 1. Measure baseline
+
+Before optimizing, always measure:
+
+```bash
+# Count tests per suite
+find tests/ app/Modules/*/Tests/ -name "*.php" | xargs grep -l "it(" | wc -l
+
+# Count by suite type
+grep -rh "it(" tests/Unit/ app/Modules/*/Tests/Unit/ --include="*.php" | wc -l
+grep -rh "it(" tests/Component/ app/Modules/*/Tests/Component/ --include="*.php" | wc -l
+grep -rh "it(" tests/Integration/ app/Modules/*/Tests/Integration/ --include="*.php" | wc -l
+
+# Count migrations
+ls database/migrations/*.php | wc -l
+
+# Count seeders
+find database/seeders database/seeder-data -name "*.php" -path "*/data/*" | wc -l
+```
+
+### 2. Identify bottlenecks
+
+The typical test lifecycle is:
+
+```
+Process Start → Migrate → Seed → [Test → Rollback] × N → Process End
+                 ↑ expensive (once per worker)
+```
+
+Check these areas in order of typical impact:
+
+| Area | What to check | Typical impact |
+|------|--------------|---------------|
+| **Migration count** | How many CREATE TABLE statements? | High if >20 |
+| **Schema dump** | Is `database/schema/` used? | High if missing |
+| **Seeder INSERT method** | Individual `save()` vs bulk insert? | Medium |
+| **Truncation** | Per-seeder truncate vs centralized? | Low (but causes correctness issues) |
+| **Connection discovery** | Dynamic `getPdo()` probing? | Low |
+| **Parallel worker setup** | Does each worker re-migrate? | High |
+
+### 3. Optimization strategies (ordered by ROI)
+
+#### A. Schema Dump (highest ROI)
+
+Laravel's `schema:dump` consolidates all migrations into one SQL file.
+Instead of running N individual CREATE TABLE migrations, it loads one SQL dump.
+
+```bash
+php artisan schema:dump --database=api_database
+# Generates database/schema/api_database-schema.sql
+```
+
+**Savings:** 58 migrations → 1 SQL load = ~10-25s per worker.
+
+#### B. Template DB Cloning (high ROI for parallel tests)
+
+Instead of each parallel worker running migrate+seed independently:
+1. Prepare ONE template database (migrate + seed)
+2. Clone template for each worker via mysqldump
+
+```bash
+# Prepare template
+php artisan migrate:fresh --database=template_db
+php artisan db:seed --database=template_db
+
+# Clone per worker
+mysqldump template_db | mysql worker_db_test_1
+```
+
+**Savings:** Eliminate per-worker migrate+seed entirely.
+
+#### C. Skip Migrate+Seed Flag (high ROI for local dev)
+
+Add a config flag to skip database setup when DB is already prepared:
+
+```php
+// config/testing.php
+'skip_migrate_seed' => EnvHelper::boolean('TESTING_SKIP_MIGRATE_SEED', false),
+```
+
+Developer workflow: `make migrate-testing` once, then `make test-quick` repeatedly.
+
+#### D. Bulk Inserts in Seeders (medium ROI)
+
+Replace individual `$model->save()` with bulk insert:
+
+```php
+// Before: N INSERT statements
+foreach ($data as $row) {
+    $model = new MyModel($row);
+    $model->save();
+}
+
+// After: 1 INSERT statement
+MyModel::insert($data);
+$models = MyModel::whereIn('id', $ids)->get();
+```
+
+#### E. Centralize Truncation (correctness fix)
+
+Per-seeder truncation is redundant after `migrate:fresh` and causes:
+- Non-deterministic ordering (lazy init triggers truncate)
+- Ghost data bugs (locally passes, CI fails)
+
+Make truncation configurable, default off:
+
+```php
+// config/testing.php
+'seed_truncate' => EnvHelper::boolean('DB_SEED_TRUNCATE', false),
+```
+
+#### F. Static Connection Discovery (cleanup)
+
+Replace dynamic `getPdo()` probing with explicit config:
+
+```php
+// config/testing.php
+'connections_to_transact' => ['api_database', 'customer_database'],
+```
+
+### 4. CI-specific optimizations
+
+- **MariaDB tmpfs:** Mount data dir on RAM disk for zero I/O latency
+- **Shared DB prep:** One CI job prepares DB, test jobs clone from it
+- **Cache test DBs:** Skip re-migration if migration files haven't changed
+- **Separate suites:** Run no-DB tests (Unit) on cheaper runners
+
+## Related project docs
+
+- `agents/roadmaps/test-performance-refactor.md` — active roadmap for this project
+- `agents/docs/seeders.md` — seeder conventions (if exists)
+
+## Output format
+
+1. Optimized test configuration or seeder with timing comparison
+2. Parallelization or caching improvements applied
+
+## Gotcha
+
+- Don't use RefreshDatabase when DatabaseTransactions suffices — full refresh is 10x slower.
+- The model forgets that parallel tests share the database — use unique identifiers in test data.
+- Seeder optimization has the highest ROI — a 2s seeder running 100 times = 200s wasted.
+- Don't add indexes to test databases just for test performance — the real fix is better test design.
+
+
+## Do NOT
+
+- Do NOT use RefreshDatabase when DatabaseTransactions works — 10x slower.
+- Do NOT run full test suite on every code change — use `--filter`.
+- Do NOT add test-only indexes — fix test design instead.
+- Do NOT disable parallel testing to "fix" flaky tests — fix the root cause.