@event4u/agent-config 1.9.1

package/.agent-src/commands/threat-model.md

@@ -0,0 +1,115 @@
+---
+name: threat-model
+skills: [threat-modeling, authz-review, security-sensitive-stop]
+description: Run a pre-implementation threat model on a proposed change — enumerates abuse cases, trust boundaries, and authorization gaps before the first line of code is written
+disable-model-invocation: true
+---
+
+# threat-model
+
+## Instructions
+
+Produce a structured threat model for the proposed change **before any code
+is written**. Dispatches to [`threat-modeling`](../skills/threat-modeling/SKILL.md)
+for abuse-case and trust-boundary analysis, and to
+[`authz-review`](../skills/authz-review/SKILL.md) whenever the change touches
+authorization, tenancy, or identity.
+
+### 1. Gather the context
+
+Collect, from the user or from the current branch:
+
+- **Change description** — what is being added or modified, in plain language
+- **Entry points** — routes, commands, queue handlers, webhooks that receive
+  the input
+- **Data touched** — tables, columns, storage, external APIs that are read
+  or written
+- **Actor** — who invokes this (authenticated user, tenant-scoped user, admin,
+  anonymous, service account, cron)
+
+If any of the four is missing, **ask the user** — do not guess. A threat model
+built on assumed context is worse than no threat model.
+
+### 2. Decide which skills to dispatch
+
+| Change touches | Skills to run |
+|---|---|
+| Any new or modified surface (default) | [`threat-modeling`](../skills/threat-modeling/SKILL.md) |
+| Permission checks, tenancy, ownership, role logic | + [`authz-review`](../skills/authz-review/SKILL.md) |
+| Secrets, tokens, credentials, signing keys | + [`security-audit`](../skills/security-audit/SKILL.md) |
+
+`threat-modeling` is always mandatory. `authz-review` is mandatory when the
+change crosses an authorization boundary — when in doubt, run it.
+
+### 3. Dispatch mode
+
+- **Sequential** (default) — `threat-modeling` first, then `authz-review` if
+  applicable. The authz findings often reference abuse cases from step 1.
+- **Parallel** — allowed only if `subagents.max_parallel` ≥ 2 in
+  `.agent-settings.yml` and both skills are available as subagents. Merge their
+  reports in step 4.
+
+Each skill produces its own structured output (abuse-case table, trust
+boundary list, authorization matrix). Do not rewrite those blocks — pass
+them through verbatim.
+
+### 4. Consolidate
+
+Produce one combined report with these sections, in order:
+
+1. **Change summary** — the four context items from step 1, restated as the
+   agent understood them
+2. **Abuse cases** — from `threat-modeling`, severity-sorted (🔴 → 🟡 → 🟢)
+3. **Trust boundaries** — entry points and what is trusted vs. untrusted at
+   each one
+4. **Authorization findings** — from `authz-review` if it ran, else a single
+   line: `authz-review skipped — change does not cross an authorization boundary`
+5. **Required controls** — the minimum set of validations, authorization
+   checks, logging, and negative tests that must exist before the change ships
+6. **Open questions** — anything the skills flagged as uncertain and the user
+   must answer before implementation starts
+
+### 5. Decide next step
+
+After the report, ask:
+
+```
+> 1. Looks right — proceed to implementation against this threat model
+> 2. Something is wrong or missing — I'll revise the context and re-run
+> 3. Stop here — threat model is the deliverable, no implementation yet
+```
+
+- On **1**: hand off to the implementation flow (e.g., `feature-plan`,
+  `bug-fix`, or direct edit) with the required-controls list pinned
+- On **2**: re-gather context and re-dispatch
+- On **3**: save the report as the deliverable, stop
+
+## Use this command when
+
+- Starting a feature that touches authentication, authorization, tenancy,
+  secrets, external input, or sensitive data
+- The [`security-sensitive-stop`](../rules/security-sensitive-stop.md) rule
+  fired and the user asks for the structured analysis
+- A PR reviewer asks for a threat model as a prerequisite
+- Before a change to a trust boundary (API endpoint, webhook, queue consumer,
+  middleware, policy)
+
+## Do NOT
+
+- NEVER skip `threat-modeling` — it is the entrypoint, not optional
+- NEVER produce a threat model on guessed context — ask for the four items
+  in step 1 if any is missing
+- NEVER merge `threat-modeling` and `authz-review` outputs into a single
+  block — each skill owns its format
+- NEVER write production code in the same turn as this command — the
+  deliverable is the report; implementation is a separate step
+- NEVER mark the change "safe" if any 🔴 abuse case has no control
+
+## See also
+
+- [`threat-modeling`](../skills/threat-modeling/SKILL.md) — abuse cases, trust boundaries
+- [`authz-review`](../skills/authz-review/SKILL.md) — end-to-end authorization analysis
+- [`data-flow-mapper`](../skills/data-flow-mapper/SKILL.md) — trace specific data through the change
+- [`blast-radius-analyzer`](../skills/blast-radius-analyzer/SKILL.md) — enumerate affected call sites
+- [`security-sensitive-stop`](../rules/security-sensitive-stop.md) — the trigger rule
+- [`minimal-safe-diff`](../rules/minimal-safe-diff.md) — keep the implementation scoped

package/.agent-src/commands/update-form-request-messages.md

@@ -0,0 +1,189 @@
+---
+name: update-form-request-messages
+skills: [laravel-validation]
+description: Sync the messages() method of a FormRequest class — add missing entries, link them to language keys, and clean up stale ones
+disable-model-invocation: true
+---
+
+# update-form-request-messages
+
+## Trigger
+
+`/update-form-request-messages [ClassName or file path]`
+
+---
+
+## Step 1: Resolve the FormRequest class
+
+**If the user attached a file or mentioned a class name explicitly** → use it.
+
+**Otherwise, ask:**
+
+> Which FormRequest class should I update?
+> Please provide the class name (e.g. `UpdateSuperUserRequest`), its namespace, or the file path.
+
+Once provided, locate the file:
+- Try `codebase-retrieval` or a `find` command to resolve the file path.
+- If multiple matches exist, list them and ask the user to pick one (numbered options).
+- If no match is found, tell the user and stop.
+
+Read the full file content.
+
+---
+
+## Step 2: Check for rules()
+
+Scan the file for a `rules()` method.
+
+- **If no `rules()` method exists** → inform the user:
+
+  > ⚠️  No `rules()` method found in `{ClassName}`. Nothing was changed.
+
+  Stop here.
+
+---
+
+## Step 3: Parse rules()
+
+Extract every `field → rules` pair from the `rules()` array.
+
+For each field, collect all rules and resolve their **rule names**:
+
+| Rule type | Example | Extracted name |
+|---|---|---|
+| String rule | `'required'` | `required` |
+| String rule with arg | `'max:250'` | `max` |
+| `Rule::` static call | `Rule::unique(...)` | `unique` |
+| `Rule::` static call | `Rule::exists(...)` | `exists` |
+| New object instance | `new Enum(...)` | `enum` (class basename, lowercased) |
+| Closure / `fn()` | `function(...) {}` | **skip** — closures call `$fail()` themselves |
+
+**Also skip these modifier rules** that never produce validation errors:
+`nullable`, `sometimes`, `bail`
+
+Build a flat list of `(field, rule_name)` pairs:
+e.g. `[('username', 'required'), ('username', 'string'), ('username', 'unique'), ...]`
+
+---
+
+## Step 4: Determine the language key domain prefix
+
+Derive the domain prefix from the class name:
+1. Strip common verb prefixes: `Create`, `Update`, `Delete`, `List`, `Get`, `Send`, `Show`, `Store`, `Filter`, `Index`
+2. Strip the `Request` suffix
+3. Convert to `snake_case`
+
+Example: `UpdateSuperUserRequest` → `SuperUser` → `super_user`
+
+Present the result and ask to confirm:
+
+> The language key prefix will be `{derived_prefix}` (e.g. `validation.{derived_prefix}.field.rule`).
+> 1. Use `{derived_prefix}` ✓
+> 2. Enter a different prefix
+
+Wait for confirmation before continuing.
+
+---
+
+## Step 5: Build the required message entries
+
+For each `(field, rule_name)` pair:
+
+- **messages() key:** `{field}.{rule_name}` (e.g. `'username.required'`)
+- **Lang key:** `validation.{domain}.{field}.{rule_name}`
+  - Wildcard fields keep their notation: `recipients.*.user_id.required`
+  - Example: `validation.super_user.username.required`
+
+---
+
+## Step 6: Read existing messages() method (if any)
+
+- If a `messages()` method exists, parse all its `key => __('...')` entries.
+- Keep track of which `(field.rule_name)` keys are already covered.
+- Note the lang key referenced in each existing `__('...')` call.
+
+---
+
+## Step 7: Add missing message entries
+
+For each required `(field, rule_name)` pair **not yet covered** by an existing messages() entry:
+
+1. **Check if the lang key already exists** in both `lang/de/validation.php` and `lang/en/validation.php`.
+2. If missing in either → generate a meaningful message:
+   - **English:** e.g. `'The email address is required.'` or `'The email address has already been taken.'`
+   - **German:** e.g. `'Die E-Mail-Adresse ist erforderlich.'` oder `'Diese E-Mail-Adresse ist bereits vergeben.'`
+   - Do **not** write `{field_label}` or `{rule_name}` literally into the lang file — replace them with the actual derived values.
+   - You may use Laravel's standard placeholders (`:attribute`, `:max`, `:min`, etc.) instead of embedding the label directly.
+   - Adapt the message text to fit the specific rule (e.g. `required` → "is required", `unique` → "has already been taken", `max` → "may not exceed :max characters")
+   - Use sensible human-readable field labels (derive from the field name: `snake_case` → "Title Case")
+3. Add the new lang key to `lang/de/validation.php` and `lang/en/validation.php` following the flat dot-notation format from `laravel-translations` rule.
+   - If a domain section comment exists for `{domain}`, insert near it. Otherwise append at the end.
+4. Add the entry to the `messages()` method: `'{field}.{rule_name}' => __('validation.{domain}.{field}.{rule_name}'),`
+
+---
+
+## Step 8: Clean up stale messages() entries
+
+Find all keys in `messages()` where `{field}.{rule_name}` is **no longer valid**:
+- The field no longer exists in `rules()`, OR
+- The rule no longer applies to that field
+
+For each stale entry:
+1. Extract the lang key from the `__('...')` call.
+2. **Search the relevant source directories** for that exact lang key string, excluding `vendor/` and `node_modules/` (e.g. `grep -r "validation.super_user.username.old_rule" app lang resources routes config`).
+3. If the lang key is **used nowhere else** → remove it from both `lang/de/validation.php` and `lang/en/validation.php`.
+4. Remove the stale key from `messages()`.
+
+---
+
+## Step 9: Write the messages() method
+
+If `messages()` did not exist → add it after `rules()`:
+
+```php
+/** @return array<string, string> */
+public function messages(): array
+{
+    return [
+        '{field}.{rule}' => __('validation.{domain}.{field}.{rule}'),
+        // ...
+    ];
+}
+```
+
+If it existed → update it in-place (keep existing entries that are still valid, add new ones, remove stale ones).
+
+Keep any spread array entries (e.g. `...parent::messages()`) at the top of the array in their original order. Below them, sort only the keyed entries by field name, then rule name within the same field.
+
+---
+
+## Step 10: Summary
+
+Print a summary table of what changed:
+
+```
+FormRequest: UpdateSuperUserRequest
+
+ADDED TO messages():
+  username.required  →  validation.super_user.username.required
+
+REMOVED FROM messages():
+  email.old_rule  (lang key removed from both lang files)
+
+UNCHANGED:
+  username.string, username.unique, ...
+
+LANG FILES UPDATED:
+  lang/en/validation.php  — +1 added, -1 removed
+  lang/de/validation.php  — +1 added, -1 removed
+```
+
+---
+
+## Rules
+
+- **Never hardcode message strings** in the FormRequest — always use `__('validation.key')`.
+- **Always update both** `lang/de/validation.php` AND `lang/en/validation.php`. One without the other is a bug.
+- **Lang keys use flat dot-notation** — never nested arrays in lang files.
+- **Do NOT commit or push.** Only apply local changes.
+- **Do NOT remove lang keys** that are still referenced anywhere else in the codebase.

package/.agent-src/commands/upstream-contribute.md

@@ -0,0 +1,171 @@
+---
+name: upstream-contribute
+skills: [upstream-contribute, skill-writing, learning-to-rule-or-skill]
+description: Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package
+disable-model-invocation: true
+---
+
+# /upstream-contribute
+
+## Input
+
+The user may provide:
+
+- A file path to a new or improved skill/rule/command
+- A description of what should be contributed
+- Nothing (auto-detect from recent work)
+
+## Steps
+
+### 1. Identify what to contribute
+
+If the user provided a file path → read it.
+If not → check for recent overrides or new skills:
+
+```bash
+ls agents/overrides/ 2>/dev/null
+find .augment/skills -name 'SKILL.md' -newer .augment/rules -maxdepth 3 2>/dev/null
+git diff --name-only HEAD~5 -- agents/overrides/ .augment/skills/ 2>/dev/null
+```
+
+Ask the user to confirm what should be contributed:
+
+```
+> Found these candidates for upstream contribution:
+>
+> 1. {file1} — {brief description}
+> 2. {file2} — {brief description}
+> 3. Something else — I'll describe it
+>
+> Which one?
+```
+
+### 2. Check universality
+
+Before proceeding, verify the content is package-worthy:
+
+- [ ] No project-specific references (domain names, local paths, FQDNs, project-specific classes)
+- [ ] Benefits ALL consumers, not just this project
+- [ ] Learning occurred 2+ times OR is clearly generalizable
+
+If project-specific content is found, ask:
+
+```
+> ⚠️ Found project-specific references: {examples}
+>
+> 1. Remove them — make it universal
+> 2. Cancel — keep as project-only override
+```
+
+### 3. Determine contribution type and target path
+
+| Type | Uncompressed target | Compressed target |
+|---|---|---|
+| **Skill** | `.agent-src.uncompressed/skills/{name}/SKILL.md` | `.agent-src/skills/{name}/SKILL.md` |
+| **Rule** | `.agent-src.uncompressed/rules/{name}.md` | `.agent-src/rules/{name}.md` |
+| **Command** | `.agent-src.uncompressed/commands/{name}.md` | `.agent-src/commands/{name}.md` |
+| **Guideline** | `.agent-src.uncompressed/guidelines/{cat}/{name}.md` | `.agent-src/guidelines/{cat}/{name}.md` |
+
+### 4. Get access to the package repo
+
+```
+> I need to create files in the agent-config package repo.
+>
+> 1. I have it cloned locally — I'll give you the path
+> 2. Clone it for me into /tmp/agent-config-upstream
+> 3. Just output the files — I'll handle it manually
+```
+
+**Option 1:** User provides path → verify it's the right repo:
+
+```bash
+cd {path} && git remote get-url origin
+# Must contain event4u-app/agent-config
+```
+
+**Option 2:**
+
+```bash
+git clone git@github.com:event4u-app/agent-config.git /tmp/agent-config-upstream
+cd /tmp/agent-config-upstream
+```
+
+**Option 3:** Skip to Step 7 (output files only).
+
+### 5. Create branch and write files
+
+```bash
+cd {package-repo}
+git checkout main && git pull
+git checkout -b {type}/{name}  # e.g. feat/skills/php-container-discovery
+```
+
+Write the **uncompressed version** (full, verbose, human-readable).
+Write the **compressed version** (token-efficient, 40-60% shorter for skills; 1:1 for rules/commands).
+
+Compressed version MUST preserve:
+
+- All code blocks (byte-for-byte)
+- YAML frontmatter (verbatim)
+- All headings
+- Validation rules, gotchas, "Do NOT" sections
+
+Frontmatter must have `source: package`.
+
+### 6. Run quality gates
+
+```bash
+task lint-skills                    # 0 FAIL required
+task check-compression              # No 🔴 errors for this file
+task generate-tools                 # Regenerate symlinks
+task consistency                    # Everything clean
+```
+
+Fix any issues before continuing.
+
+### 7. Present result
+
+**If Option 1 or 2** (working in package repo):
+
+```
+> ✅ Files created in {package-repo}:
+>
+> - `.agent-src.uncompressed/{type}/{name}` (uncompressed)
+> - `.agent-src/{type}/{name}` (compressed)
+>
+> Quality gates: {pass/fail summary}
+>
+> 1. Commit and push — I'll create the PR
+> 2. Commit only — I'll push later
+> 3. Review the files first
+```
+
+**If Option 3** (manual):
+
+Show both file contents in copyable fenced blocks with full paths as headers.
+
+### 8. Create PR (if user chose Option 1 in Step 7)
+
+```bash
+git add .
+git commit -m "{type}({scope}): add {name}
+
+{brief description of what it does and why it's universal}"
+git push -u origin {branch}
+```
+
+Create PR via GitHub API with the package's PR template.
+Fill in all gates (Promotion, Quality, Universality, Completeness).
+
+### 9. Remind about local override cleanup
+
+```
+> 📝 After the PR is merged and you update the package in this project:
+>
+> ```bash
+> rm agents/overrides/{type}/{name}.md
+> composer update event4u/agent-config  # or: npm update
+> ```
+>
+> The shared version will then replace your local override.
+```

package/.agent-src/contexts/augment-infrastructure.md

@@ -0,0 +1,181 @@
+# Context: Augment Infrastructure
+
+> The complete `.augment/` directory structure — what it contains, how it's organized, and how agents use it.
+
+**Type:** Infrastructure
+**Created:** 2026-03-20
+**Last Updated:** 2026-03-25
+
+## Overview
+
+The `.augment/` directory is a **shared Composer package** (read-only at project level) that provides
+the agent infrastructure for all projects. It contains reusable skills, rules, commands,
+guidelines, templates, and contexts that define how AI agents behave across the entire organization.
+
+Projects customize this shared behavior through `agents/overrides/` — never by editing `.augment/` directly.
+
+## Directory Structure
+
+```
+.augment/
+├── rules/           ← Always-active behavior rules (auto-loaded by Augment)
+├── skills/          ← Reusable skill definitions (loaded on-demand by topic)
+├── commands/        ← Slash commands (interactive workflows)
+├── guidelines/      ← Coding guidelines organized by language
+│   └── php/         ← PHP-specific guidelines and patterns
+│       └── patterns/
+├── templates/       ← Document templates (features, roadmaps, contexts, overrides)
+│   └── overrides/   ← Templates for creating override files
+└── contexts/        ← Shared context documents about the .augment/ system itself
+```
+
+## Component Types
+
+### Rules (`.augment/rules/`)
+
+**Always active.** Loaded automatically for every conversation.
+Define hard constraints: coding standards, Docker usage, language preferences, scope control.
+
+**Always-active:**
+
+| Rule | Purpose |
+|---|---|
+| `php-coding.md` | PHP coding standards (strict types, Math helper, comparisons) |
+| `token-efficiency.md` | Redirect tool output to files, read only summaries, minimal output |
+| `verify-before-complete.md` | Run verification before claiming completion |
+| `user-interaction.md` | Numbered options, progress indicators |
+| `model-recommendation.md` | Detect model, suggest switch for task type (opus/sonnet/gpt) |
+| `language-and-tone.md` | German "Du", English code comments, icon spacing |
+| `ask-when-uncertain.md` | When in doubt, ask the user — never guess or assume |
+| `scope-control.md` | Stay within scope, no commit/push without permission |
+| `guidelines.md` | Check coding guidelines before writing code |
+| `commands.md` | Execute slash commands immediately — no questions, no opinions |
+
+**Auto-loaded by topic:**
+
+| Rule | Purpose |
+|---|---|
+| `quality-workflow.md` | PHP (PHPStan → Rector → PHPStan) and JS/TS pipelines |
+| `downstream-changes.md` | After every edit, find and update ALL callers, tests, imports |
+| `docs-sync.md` | Keep docs in sync when skills/rules change |
+| `context-hygiene.md` | 3-failure rule, state dumps |
+| `architecture.md` | Architecture principles, file placement |
+| `docker-commands.md` | All PHP commands run inside Docker containers |
+| `commit-conventions.md` | Conventional Commits format |
+| `dev-efficiency.md` | Running CLI commands with verbose output — git, tests, linters, docker, build tools |
+| `e2e-testing.md` | Playwright E2E tests — locators, assertions, Page Objects, CI |
+| `lang-files.md` | Laravel lang files, both de/ and en/ always in sync |
+| `rtk.md` | Using rtk for token-efficient CLI output filtering |
+| `agent-docs.md` | When to read/create/update documentation |
+| `augment-portability.md` | Everything in `.augment/` must be project-agnostic |
+| `roadmap-progress-sync.md` | Checkbox edits in `agents/roadmaps/*.md` must trigger `task roadmap-progress` in the same response |
+
+### Skills (`.augment/skills/`)
+
+**On-demand.** Loaded when the agent needs specific expertise.
+Each skill is a directory with a `SKILL.md` file defining behavior, patterns, and rules.
+
+Skills organized by domain:
+
+| Category | Skills |
+|---|---|
+| **PHP/Laravel** | `php`, `php-coder`, `laravel`, `eloquent`, `laravel-validation`, `php-service`, `dto-creator`, `artisan-commands`, `laravel-horizon`, `laravel-mail`, `laravel-middleware`, `laravel-notifications`, `laravel-pennant`, `laravel-pulse`, `laravel-reverb`, `laravel-scheduling` |
+| **API** | `api-endpoint`, `api-design`, `api-versioning`, `api-testing`, `openapi` |
+| **Analysis** | `analysis-autonomous-mode`, `universal-project-analysis`, `project-analysis-laravel`, `bug-analyzer`, `security-audit`, `performance-analysis` |
+| **Testing** | `pest-testing`, `test-generator`, `test-performance`, `php-debugging`, `playwright-testing` |
+| **Frontend** | `javascript`, `typescript`, `vue`, `react`, `nextjs`, `nuxt`, `tailwind`, `livewire`, `flux`, `blade-ui`, `fe-design` |
+| **Infrastructure** | `docker`, `aws-infrastructure`, `terraform`, `terragrunt`, `devcontainer`, `github-ci`, `cloudflare-workers`, `traefik` |
+| **Data** | `database`, `migration-creator`, `multi-tenancy`, `performance`, `sql-writing` |
+| **Jobs/Events** | `jobs-events`, `logging-monitoring`, `grafana`, `websocket` |
+| **Packages** | `composer`, `composer-packages`, `npm`, `npm-packages` |
+| **Design** | `dashboard-design`, `design-review`, `fe-design` |
+| **Agent System** | `agent-docs-writing`, `agents-audit`, `context-create`, `commands`, `copilot-config`, `copilot-agents-optimization`, `feature-planning`, `file-editor`, `guidelines`, `mcp`, `override-management`, `project-docs`, `roadmap-management`, `module-management`, `naming`, `project-analyzer`, `sequential-thinking`, `skill-reviewer` |
+| **Workflow** | `git-workflow`, `merge-conflicts`, `code-review`, `code-refactoring`, `bug-analyzer`, `security`, `adversarial-review`, `dependency-upgrade`, `quality-tools` |
+| **Other** | `graphql`, `jira-integration`, `mobile`, `sentry-integration`, `wordpress`, `microservices`, `technical-specification` |
+
+### Commands (`.augment/commands/`)
+
+**Interactive workflows.** Triggered by the user or other commands.
+Each command is a `.md` file with a step-by-step flow.
+
+Commands organized by workflow:
+
+| Category | Commands |
+|---|---|
+| **Features** | `feature-dev`, `feature-plan`, `feature-explore`, `feature-refactor`, `feature-roadmap` |
+| **Bugs** | `bug-investigate`, `bug-fix` |
+| **Contexts** | `context-create`, `context-refactor` |
+| **Modules** | `module-create`, `module-explore` |
+| **Roadmaps** | `roadmap-create`, `roadmap-execute` |
+| **Quality** | `quality-fix`, `review-changes`, `prepare-for-review`, `update-form-request-messages`, `fix-seeder` |
+| **CI/PR** | `fix-ci`, `create-pr`, `create-pr-description`, `fix-pr-comments`, `fix-pr-bot-comments`, `fix-pr-developer-comments` |
+| **Testing** | `tests-create`, `tests-execute` |
+| **E2E** | `e2e-plan`, `e2e-heal` |
+| **Agents** | `agents-prepare`, `agents-audit`, `agents-cleanup`, `copilot-agents-optimize`, `agent-handoff`, `agent-status`, `optimize-agents`, `optimize-augmentignore`, `optimize-skills`, `optimize-rtk-filters` |
+| **Overrides** | `override-create`, `override-manage` |
+| **Config** | `config-agent-settings`, `commit` |
+| **Packages** | `package-test`, `package-reset` |
+| **Project** | `project-analyze`, `project-health`, `jira-ticket` |
+
+### Guidelines (`.augment/guidelines/`)
+
+**Coding conventions** organized by language/domain. PHP and E2E testing.
+
+```
+guidelines/php/
+├── php.md              ← General PHP conventions
+├── controllers.md      ← Single-action controllers, OpenAPI
+├── eloquent.md         ← Getter/setter pattern, casts
+├── validations.md      ← FormRequest conventions
+├── resources.md        ← API Resource versioning (v1/v2)
+├── jobs.md             ← Queue jobs, Horizon tags
+├── git.md              ← Branch naming, commit messages
+├── patterns.md         ← Pattern index (links to patterns/)
+└── patterns/           ← 9 design pattern guides
+    ├── service-layer.md
+    ├── repositories.md
+    ├── dtos.md
+    ├── dependency-injection.md
+    ├── strategy.md
+    ├── factory.md
+    ├── policies.md
+    ├── events.md
+    └── pipelines.md
+guidelines/e2e/
+└── playwright.md        ← Playwright E2E best practices
+```
+
+Each guideline has a consistent header with **Related Skills**, **Related Rules**, and **Related Guidelines**.
+
+### Templates (`.augment/templates/`)
+
+**Document structure definitions** for features, roadmaps, contexts, and overrides.
+
+| Template | Creates files in |
+|---|---|
+| `features.md` | `agents/features/` or module `agents/features/` |
+| `roadmaps.md` | `agents/roadmaps/` or module `agents/roadmaps/` |
+| `contexts.md` | `agents/contexts/` or module `agents/contexts/` |
+| `overrides/rule.md` | `agents/overrides/rules/` |
+| `overrides/skill.md` | `agents/overrides/skills/` |
+| `overrides/command.md` | `agents/overrides/commands/` |
+| `overrides/guideline.md` | `agents/overrides/guidelines/` |
+| `overrides/template.md` | `agents/overrides/templates/` |
+
+### Contexts (`.augment/contexts/`)
+
+**Shared context documents** about the `.augment/` system itself.
+These help agents understand the infrastructure they operate in.
+
+Unlike project contexts (`agents/contexts/`), these are part of the shared package
+and describe the agent system, not the project's business domain.
+
+## Key Principles
+
+1. **`.augment/` is read-only** — it's a shared resource across all projects
+2. **Project customization via `agents/overrides/`** — extend or replace shared behavior
+3. **Rules are always active**, skills are on-demand, commands are user-triggered
+4. **Guidelines have cross-references** — each links to related skills and rules
+5. **Templates are the single source of truth** for document structure
+6. **All content in English** — code comments, documentation, agent files
+