@event4u/agent-config 1.20.0 → 1.22.0

package/.agent-src/rules/commit-policy.md

@@ -5,16 +5,11 @@ description: "Commit policy — never commit and never ask about committing unle
 alwaysApply: true
 source: package
 load_context:
-  - .agent-src.uncompressed/contexts/authority/commit-mechanics.md
+  - ../contexts/authority/commit-mechanics.md
 ---
 
 # Commit Policy
 
-Local commits do not change remote state, but committing prematurely
-makes review harder. This is the **canonical** rule for committing,
-referenced by [`autonomous-execution`](autonomous-execution.md),
-[`scope-control`](scope-control.md), and the roadmap commands.
-
 ## The Iron Law
 
 ```
@@ -22,61 +17,35 @@ NEVER COMMIT. NEVER ASK ABOUT COMMITTING.
 EXCEPTIONS ARE EXPLICIT, NOT INFERRED.
 ```
 
-Applies regardless of `personal.autonomy`, conversation momentum, or
-"but it's a clean stopping point". Default is **no commit, no
-question**.
+Applies regardless of `personal.autonomy`, conversation momentum, or "clean stopping point". Default: **no commit, no question**.
 
 ## Exceptions — when committing IS allowed
 
-Exactly four ways the agent may commit:
+Exactly four:
 
-1. **User says so this turn** — explicit phrase like "commit this now",
-   "go ahead and commit". Permission is for **this commit only**, not
-   standing.
-2. **Standing instruction not yet revoked** — user said earlier in
-   the conversation "commit after every phase" or similar, and has not
-   revoked it. Cache and honor.
-3. **Commit command invoked** — `/commit` (with confirmation) or
-   `/commit-in-chunks` (auto-split, no confirmation).
-4. **Roadmap authorization** — the roadmap file lists explicit commit
-   steps and the user invoked roadmap execution.
+1. **User says so this turn** — "commit this now", "go ahead and commit". This commit only, not standing.
+2. **Standing instruction not yet revoked** — "commit after every phase" earlier in the conversation; cache and honor.
+3. **Commit command invoked** — `/commit` (with confirmation) or `/commit:in-chunks` (auto-split, no confirmation).
+4. **Roadmap authorization** — roadmap file lists explicit commit steps and the user invoked roadmap execution.
 
-Anything else → no commit. Hard Floor (bulk deletions, infra changes)
-still fires on top of any exception — see
-[`commit-mechanics`](../contexts/authority/commit-mechanics.md) for
-the diff triggers and the roadmap-authorized commit flow.
+Anything else → no commit. Hard Floor (bulk deletions, infra changes) still fires on top of any exception — see [`commit-mechanics`](../contexts/authority/commit-mechanics.md) for diff triggers and roadmap-authorized commit flow.
 
 ## NEVER ask about committing
 
-Asking "should I commit this?", "do we want to commit?", or any
-variant is **forbidden**. The user invokes a command or says so
-explicitly. Don't surface a commit option in numbered-options blocks
-unless the rest of the message would be incomplete without it.
+"Should I commit this?" / "do we want to commit?" — **forbidden**. The user invokes a command or says so explicitly. Don't surface a commit option in numbered-options blocks unless the rest of the message would be incomplete without it.
 
-Quoted commit phrases (chat-log paste, log excerpt, roadmap snippet)
-are **not** permission — see
-[`commit-mechanics`](../contexts/authority/commit-mechanics.md)
-§ Speech-act check.
+Quoted commit phrases (chat-log paste, log excerpt, roadmap snippet) are **not** permission — see [`commit-mechanics § Speech-act check`](../contexts/authority/commit-mechanics.md).
 
 ## NEVER write commit steps into roadmaps unsolicited
 
-When **creating** a roadmap (via `/roadmap-create`,
-`/feature-roadmap`, or any roadmap-producing flow), do **not** include
-commit steps unless the user explicitly requested them. Commits are a
-delivery decision; roadmaps plan **work**.
+When **creating** a roadmap (`/roadmap-create`, `/feature-roadmap`, any roadmap-producing flow) — do **not** include commit steps unless the user explicitly requested them. Commits are a delivery decision; roadmaps plan **work**.
 
-If the user explicitly wants commit steps in the roadmap, write them
-clearly and unambiguously (e.g. "Commit phase X: chore: …").
+If the user explicitly wants commit steps, write them clearly (e.g. "Commit phase X: chore: …").
 
 ## See also
 
-- [`autonomous-execution`](autonomous-execution.md) — when to suppress
-  trivial questions; this rule survives the suppression.
-- [`no-cheap-questions`](no-cheap-questions.md) — commit asks are
-  cheap by construction; this rule is the canonical Iron Law, the
-  cheap-questions rule cites it and refuses to surface the option.
-- [`scope-control`](scope-control.md) — git-ops permission gate
-  (push, merge, branch, PR, tag stay separately permission-gated).
+- [`autonomous-execution`](autonomous-execution.md) — trivial-question suppression; this rule survives the suppression.
+- [`no-cheap-questions`](no-cheap-questions.md) — commit asks are cheap by construction; this rule is the canonical Iron Law.
+- [`scope-control`](scope-control.md) — git-ops permission gate (push, merge, branch, PR, tag).
 - [`/commit`](../commands/commit.md) — split and commit with confirmation.
-- [`/commit-in-chunks`](../commands/commit-in-chunks.md) — auto-split
-  and commit without confirmation.
+- [`/commit:in-chunks`](../commands/commit/in-chunks.md) — auto-split, no confirmation.

package/.agent-src/rules/context-hygiene.md

@@ -4,6 +4,11 @@ tier: "1"
 alwaysApply: false
 description: "When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers"
 source: package
+triggers:
+  - intent: "long conversation"
+  - intent: "tool loop"
+  - intent: "fresh chat"
+  - keyword: "3-failure"
 ---
 
 # Context Hygiene

package/.agent-src/rules/direct-answers.md

@@ -8,8 +8,7 @@ source: package
 
 # Direct Answers
 
-Three Iron Laws govern every reply. They override conversation
-momentum, politeness defaults, and the urge to fill space.
+Three Iron Laws govern every reply.
 
 ## Iron Law 1 — No Flattery
 
@@ -19,11 +18,10 @@ NEVER PRAISE THE USER'S IDEA TO MAKE THEM HAPPY.
 ANSWER THE SUBSTANCE. SHIP THE TRUTH.
 ```
 
-- No positive adjectives about user, question, idea, or work product as opener.
-- No subjective judgments on user's code/decisions ("nice approach", "boring") unless evaluation was asked.
-- "Good catch" / "you're right" only when literally true and load-bearing.
-- Acknowledge mistakes without performative apologies — one sentence, switch behavior.
-- Failure mode — praise hedging bad news; drop the cushion, deliver the news.
+- No positive-adjective opener about user / question / idea / work.
+- No subjective judgment on user code unless evaluation was asked.
+- "Good catch" / "you're right" only when literally true.
+- Mistakes — one-sentence acknowledge, switch behavior, no apology theatre.
 
 ## Iron Law 2 — No Invented Facts (severity-tiered)
 
@@ -33,16 +31,14 @@ THE MORE LOAD-BEARING THE CLAIM, THE HARDER YOU VERIFY.
 WHEN VERIFICATION IS NOT WORTH THE COST → ASK.
 ```
 
-| Severity | Required action |
+| Severity | Action |
 |---|---|
-| **High — load-bearing** (file paths, signatures, version numbers, security claims, "this test passes") | MUST verify with `view`, `grep`, `codebase-retrieval`, or fresh command output. Too expensive → ask. |
-| **Medium — project-shape** ("uses X for Y", conventions, file location) | Verify if one tool call reaches it; otherwise hedge: *"I'd guess X — not checked"*. |
-| **Low — well-known idioms** (generic language/framework idioms, public APIs) | Inference acceptable. Mark as inference if not 100% sure. |
+| **High** — load-bearing (paths, signatures, versions, security, "this passes") | Verify with `view` / `grep` / `codebase-retrieval` / fresh output. Too expensive → ask. |
+| **Medium** — project-shape (conventions, file location) | One-tool-call verify, else hedge: *"I'd guess X — not checked"*. |
+| **Low** — well-known idioms | Inference OK; mark as inference if not 100% sure. |
 
-Examples + hedge-language patterns:
-[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
-Override: "just guess", "rough estimate is fine", "skip the verify"
-→ drop to Low for that turn.
+Override: "just guess" / "rough estimate" / "skip verify" → drop to Low for that turn.
+Examples + hedge patterns: [`asking-and-brevity-examples § severity`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--severity-tiered-claim-examples).
 
 ## Iron Law 3 — Brevity by Default
 
@@ -51,49 +47,24 @@ THE SHORTEST REPLY THAT FULLY ANSWERS THE QUESTION IS THE RIGHT REPLY.
 LONG ANSWERS ARE A FAILURE MODE, NOT A SIGN OF EFFORT.
 ```
 
-- Skip restating the user's question.
-- Skip announcing intent ("Let me…", "I will now…") — just do.
+- Skip restating the question; skip "Let me…" intent announcements.
 - Skip explaining tool use — the call result speaks.
 - Skip post-hoc summary unless rechecking a decision.
-- Multi-step → bullets, not paragraphs.
-- One-true-answer question → one sentence + the answer.
+- Multi-step → bullets. One-true-answer → one sentence.
 
-`token-efficiency` covers the loop side; this rule covers per-reply
-length. **Never overrides** `user-interaction` (numbered options stay)
-or command-mandated steps.
+Never overrides `user-interaction` (numbered options stay) or command-mandated steps.
 
 ## Emoji Scope — functional markers only
 
-**Whitelist:** mode markers from `role-mode-adherence`;
-CLI status `❌` / `✅` / `⚠️` (two-space rule from `language-and-tone`);
-roadmap checkboxes `[x]` / `[~]` / `[-]`.
+**Whitelist:** mode markers (`role-mode-adherence`); CLI status `❌` / `✅` / `⚠️`; roadmap checkboxes `[x]` / `[~]` / `[-]`.
+**Blacklist:** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍); empathy (❤️, 🤗, 😊); section dividers; reaction emojis. Unsure → blacklist.
 
-**Blacklist (never in prose):** opening flair (✨, 🚀, 🎉, 💡, 🔥, 👍);
-empathy (❤️, 🤗, 😊); section dividers, headline ornaments, reaction
-emojis. Unsure → assume blacklist.
+## Failure modes & examples
 
-## Failure modes
-
-Trigger phrases + in-language correction pattern:
-[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--failure-modes-the-user-will-call-out).
-On call-out: acknowledge once in the user's language, switch, no
-excuses (mirrors `language-and-tone` § slip handling).
+Trigger phrases + correction pattern: [`asking-and-brevity-examples § failure-modes`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#direct-answers--failure-modes-the-user-will-call-out).
+Pattern Memory (wrong / right / why): [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md).
+Outcome baseline: [`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
 
 ## Interactions
 
-- `language-and-tone` — language mirroring, `.md` always English,
-  CLI-icon two-space rule.
-- `ask-when-uncertain` — resolution surface for Iron Law 2 gaps.
-- `think-before-action` — how to verify code-behavior claims.
-- `verify-before-complete` — completion-claim evidence gate.
-- `token-efficiency` — loop-side brevity.
-- `user-interaction` — numbered-options Iron Law overrides brevity.
-
-## Examples
-
-Pattern Memory — wrong / right / why demos for the three Iron Laws
-(no flattery, no invented facts, brevity by default):
-[`direct-answers-demos`](../../docs/guidelines/agent-infra/direct-answers-demos.md)
-(flattery openers, hedged claims, post-hoc-summary creep,
-emoji scope). Outcome baseline locked at
-[`tests/golden/outcomes/direct_answers.json`](../../tests/golden/outcomes/direct_answers.json).
+`language-and-tone` · `ask-when-uncertain` · `think-before-action` · `verify-before-complete` · `token-efficiency` · `user-interaction` (overrides brevity).

package/.agent-src/rules/docker-commands.md

@@ -1,54 +1,20 @@
 ---
 type: "auto"
 tier: "3"
-alwaysApply: false
 description: "Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution"
 source: package
+triggers:
+  - keyword: "docker"
+  - keyword: "artisan"
+  - keyword: "composer"
+  - phrase: "inside the container"
+routes_to:
+  - "skill:docker"
 ---
 
-# Docker Container Commands
+# Docker Commands
 
-All PHP commands (PHPStan, Rector, Composer, PHPUnit, Artisan) must be executed **inside the Docker container**, not on the host.
+**Iron Law.** Run PHP / artisan / composer / phpstan / rector / ecs / phpunit inside the project container, never on the host.
 
-## Container Detection
-
-Detect the correct PHP container service name from `docker-compose.yml` / `compose.yaml`.
-Read the compose file to find the PHP service name — it varies per project.
-
-Use `docker compose exec -T <service> ...` for non-interactive commands (scripts, CI).
-Use `make console` to enter the container interactively (if available).
-
-## Tooling Detection
-
-Check if `artisan` exists in the project root:
-
-- **Laravel** (`artisan` exists): `php artisan test`, `vendor/bin/phpstan analyse`, `vendor/bin/rector process`
-- **Composer** (no `artisan`): `vendor/bin/phpunit`, `vendor/bin/phpstan analyse`, `vendor/bin/rector process`
-
-## Examples (Laravel project)
-
-```bash
-docker compose exec -T <php-service> vendor/bin/phpstan analyse
-docker compose exec -T <php-service> vendor/bin/rector process
-docker compose exec -T <php-service> vendor/bin/ecs check --fix
-docker compose exec -T <php-service> php artisan test
-```
-
-## Examples (Composer project)
-
-```bash
-docker compose exec -T <php-service> vendor/bin/phpstan analyse
-docker compose exec -T <php-service> vendor/bin/rector process
-docker compose exec -T <php-service> vendor/bin/ecs check --fix
-docker compose exec -T <php-service> vendor/bin/phpunit
-```
-
-## Build / Task Runner
-
-Before using raw `docker compose exec` commands, check if the consumer
-project ships a `Makefile` for common targets (e.g. `make console`,
-`make test`, `make phpstan`). Read the Makefile first to discover
-available shortcuts. If the project uses a different task runner,
-inspect its config file before defaulting to raw `docker compose exec`.
-
-Frontend commands (npm, webpack) run on the host or in the node container.
+Body migrated to `skill:docker` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/docs-sync.md

@@ -3,64 +3,18 @@ type: "auto"
 tier: "2a"
 description: "Keeping .augment/ contexts, counts, and cross-references in sync when creating, renaming, or deleting skills, commands, rules, guidelines, templates, or any agent infrastructure files"
 source: package
-load_context:
-  - .agent-src.uncompressed/contexts/communication/rules-auto/docs-sync-mechanics.md
+triggers:
+  - path_prefix: ".agent-src.uncompressed/"
+  - path_prefix: ".augment/"
+  - keyword: "rename"
+  - keyword: "delete"
+routes_to:
+  - "skill:agent-docs-writing"
 ---
 
 # Docs Sync
 
-## Rule
+**Iron Law.** On any add / rename / delete of skill / rule / command / guideline, update counts and cross-references in the same edit.
 
-**CRITICAL — ZERO TOLERANCE:** When a file in `.augment/` is **created, renamed, or deleted**,
-or its **name, description, scope, or counts change**, all related files **must be updated
-in the same response** — not later, not in a follow-up, not when reminded.
-
-A new rule/skill/command without its index entry, count update, and context update is **incomplete work**.
-
-**Mandatory sequence when creating/deleting any `.augment/` file:**
-1. Create/delete the file
-2. **Immediately** update `contexts/augment-infrastructure.md` (counts + category tables)
-3. Check cross-references in contexts and routing hints (inline "see X skill" references)
-4. If a **skill** was added/renamed/deleted: update distribution manifests
-5. If a **hook** was added/renamed/deleted: update hook registries
-6. If **content** changed: run the consistency grep across other artefacts
-
-Steps 2–6 are NOT optional. Do NOT present the result to the user until all steps are done.
-
-**Two modes:**
-- **Reactive** (automatic): Triggered by add/remove/rename or scope/description/count changes → sync counts, contexts, cross-references, manifests, registries.
-- **Proactive** (on demand): Full audit → find duplicates, thin skills, redundancy, stale content → fix or merge. Ask before destructive actions.
-
-## Settings template sync
-
-When a skill, rule, or command **reads a new setting** from `.agent-settings.yml` that does not yet
-exist in `.augment/templates/agent-settings.md`:
-
-1. **Add the key** with its default value to the template block.
-2. **Add a row** to the Settings Reference table.
-3. **Add a comment** above the key explaining what it does.
-4. **Update the local `.agent-settings.yml`** — add the new key with its default value.
-   Preserve all existing values, apply template order and comments. Follow the
-   [section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
-   so the user benefits immediately without running a separate command.
-
-**This step is mandatory.** If the template gains a new key but the local `.agent-settings.yml`
-is not updated, the user cannot discover the new setting exists.
-
-## Lookup tables and details — see mechanics
-
-The exact "what to update" tables, cross-reference targets,
-distribution-manifest update tables (`marketplace.json` etc.), hook
-registry update tables (`__init__.py`, consumer-settings JSON), the
-failure mode that motivated the manifest section, and the content
-consistency `grep` snippet all live in
-[`contexts/communication/rules-auto/docs-sync-mechanics.md`](../contexts/communication/rules-auto/docs-sync-mechanics.md).
-Pull it whenever a sync trigger fires.
-
-## Do NOT
-
-- Do NOT rewrite entire files — only update the affected entries.
-- Do NOT ask the user for permission — this is an automatic maintenance step, like updating imports.
-- Do NOT skip cross-reference updates — stale links are worse than no links.
-- Do NOT present a new `.augment/` file to the user without having completed all sync steps first.
-- Do NOT defer sync to a "follow-up" — it must happen in the same response as the creation/deletion.
+Body migrated to `skill:agent-docs-writing` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/downstream-changes.md

@@ -4,6 +4,11 @@ tier: "2b"
 alwaysApply: false
 description: "After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation"
 source: package
+triggers:
+  - intent: "after code edit"
+  - keyword: "callers"
+  - keyword: "imports"
+  - keyword: "downstream"
 ---
 
 # Downstream Changes

package/.agent-src/rules/e2e-testing.md

@@ -1,54 +1,19 @@
 ---
 type: "auto"
 tier: "3"
-alwaysApply: false
 description: "Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention"
 source: package
+triggers:
+  - keyword: "playwright"
+  - keyword: "e2e"
+  - phrase: "page object"
+routes_to:
+  - "command:e2e-heal"
 ---
 
 # E2E Testing
 
-## Before writing E2E tests
+**Iron Law.** Playwright E2E: stable locators, no `waitForTimeout`, Page Objects for shared flows, fixtures over `beforeEach`.
 
-1. **Read the guideline** — `../../docs/guidelines/e2e/playwright.md` for all conventions and patterns.
-2. **Check existing tests** — match the project's structure, fixtures, and Page Object patterns.
-3. **Check `playwright.config.ts`** — base URL, browsers, timeouts, projects.
-
-## Locator rules
-
-- **Always prefer semantic locators**: `getByRole` > `getByLabel` > `getByText` > `getByTestId` > CSS.
-- Never use auto-generated class names, dynamic IDs, or XPath.
-- If no semantic locator works, add a `data-testid` to the component.
-
-## Assertion rules
-
-- **Always use web-first assertions** (`toBeVisible`, `toHaveText`, `toHaveURL`).
-- Never use `expect(await ...)` pattern — it doesn't auto-retry.
-- Never use `page.waitForTimeout()` — wait for a condition instead.
-
-## Test structure rules
-
-- One test = one user workflow or behavior.
-- Tests must be **fully isolated** — no shared state, no execution order dependency.
-- Page Objects contain **actions only**, never assertions.
-- Use **fixtures** for reusable setup (auth, page objects, test data).
-- Use **API calls** for test data setup — faster and more reliable than UI interactions.
-
-## CI rules
-
-- Set `workers: 1` in CI for stability.
-- Set `retries: 2` in CI, `0` locally.
-- Set `forbidOnly: !!process.env.CI` to prevent `.only` in CI.
-- Collect `trace: 'on-first-retry'` — not on every run.
-- Only install browsers you need (`npx playwright install chromium --with-deps`).
-- Upload `playwright-report/` as CI artifact.
-
-## Quality checks
-
-Before claiming E2E tests are complete:
-
-1. All tests pass locally: `npx playwright test`
-2. No `waitForTimeout` calls in the code.
-3. No CSS/XPath selectors where semantic locators work.
-4. No `.only` left in test files.
-5. Page Objects have no assertions.
+Body migrated to `command:e2e-heal` (per P4 of `road-to-kernel-and-router.md`).
+Trigger-set above activates this routing under the `balanced` and `full` profiles.

package/.agent-src/rules/guidelines.md

@@ -4,88 +4,26 @@ tier: "3"
 description: "Writing or reviewing code — check relevant guideline before writing or reviewing code"
 alwaysApply: false
 source: package
+load_context:
+  - ../contexts/communication/rules-auto/guidelines-mechanics.md
+triggers:
+  - intent: "writing code"
+  - intent: "reviewing code"
+  - keyword: "convention"
 ---
 
 # Guidelines
 
-Coding guidelines live in `.augment/guidelines/` organized by language.
-**Always check the relevant guideline** before writing or reviewing code.
-
-## Available Guidelines
-
-### PHP (`../../docs/guidelines/php/`)
-
-| File | Topic |
-|---|---|
-| `php.md` | General PHP style — strict types, naming, comparisons, early returns, JSON handling |
-| `controllers.md` | Thin controllers, single responsibility, delegation to services |
-| `eloquent.md` | Model conventions, relationships, scopes, accessors/mutators |
-| `validations.md` | FormRequest patterns, custom rules, validation structure |
-| `resources.md` | API Resource conventions, response structure |
-| `jobs.md` | Queue job patterns, serialization, retry strategies |
-| `git.md` | Branch naming, commit messages, PR conventions |
-| `api-design.md` | API conventions — response format, status codes, pagination, error handling |
-| `artisan-commands.md` | Console command conventions — naming, structure, safety, scheduling |
-| `blade-ui.md` | Blade template conventions — views, components, forms, escaping |
-| `database.md` | Database conventions — indexing, query optimization, migrations, transactions |
-| `flux.md` | Flux UI component conventions — usage, variants, forms, Livewire integration |
-| `livewire.md` | Livewire component conventions — state, actions, forms, performance, Alpine.js |
-| `logging.md` | Logging conventions — levels, structured context, Sentry patterns |
-| `naming.md` | Naming conventions — classes, database, routes, variables, modules, agent infra |
-| `performance.md` | Performance conventions — caching, Redis, eager loading, response time targets |
-| `security.md` | Security conventions — auth, authorization, SQL injection, XSS, CSRF, headers |
-| `sql.md` | Raw SQL conventions — parameterization, MariaDB syntax, common mistakes |
-| `websocket.md` | WebSocket conventions — Broadcasting, channel types, connection management |
-| `patterns.md` | Design patterns index (links to `patterns/` subdirectory) |
-
-### PHP Patterns (`../../docs/guidelines/php/patterns/`)
-
-| File | Pattern |
-|---|---|
-| `service-layer.md` | Service classes, business logic encapsulation |
-| `repositories.md` | Repository pattern, query encapsulation |
-| `dtos.md` | Data Transfer Objects, SimpleDto conventions |
-| `dependency-injection.md` | Constructor injection, service container |
-| `events.md` | Event/Listener patterns, dispatching |
-| `policies.md` | Authorization policies, gate definitions |
-| `factory.md` | Factory pattern usage |
-| `pipelines.md` | Laravel Pipeline pattern |
-| `strategy.md` | Strategy pattern implementation |
-
-### E2E (`../../docs/guidelines/e2e/`)
-
-Playwright best practices, Page Objects, fixtures, CI.
-
-### Agent Infrastructure (`../../docs/guidelines/agent-infra/`)
-
-| File | Topic |
-|---|---|
-| `size-and-scope.md` | Size limits and scope boundaries for rules, skills, commands, guidelines, AGENTS.md, copilot-instructions.md |
-| `output-patterns.md` | Redirect/Summarize/Target pattern, targeted operations, tool-first policy, general CLI rules |
+Coding guidelines live under `docs/guidelines/` organized by language. **Always check the relevant guideline** before writing or reviewing code.
 
 ## How guidelines work
 
-- **Guidelines** = detailed coding conventions (reference material, read on demand)
-- **Rules** = always-active behavior constraints (auto-loaded every conversation)
-- **Skills** = agent capabilities and workflows (matched by topic)
-
-Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically.
-Skills reference guidelines when performing related tasks.
-
-## Boundary: Guidelines vs Skills
-
-- Guidelines contain **conventions and reference knowledge**. Skills contain **executable workflows**.
-- A skill may reference a guideline for conventions, but must NOT outsource its core execution steps to a guideline.
-- Do NOT move a skill's operational core (procedure, validation, decision logic) into a guideline.
-- If a skill becomes "go read the guideline", it has lost its purpose — restore the workflow.
-
-## Adding new guidelines
+- **Guidelines** = detailed coding conventions (reference material, read on demand).
+- **Rules** = always-active behavior constraints (auto-loaded every conversation).
+- **Skills** = agent capabilities and workflows (matched by topic).
 
-When a new language or framework is introduced, create a directory:
-```
-.augment/guidelines/{language}/
-```
+Guidelines are the "how to write code" docs. Rules enforce critical subsets automatically. Skills reference guidelines when performing related tasks.
 
-Follow the existing PHP structure as a template.
+## Index — see mechanics
 
-Read the specific guideline file on demand — don't memorize the full list.
+The full file index (PHP, PHP patterns, E2E, agent-infra) plus the guidelines-vs-skills boundary and the "adding new guidelines" template live in [`contexts/communication/rules-auto/guidelines-mechanics.md`](../contexts/communication/rules-auto/guidelines-mechanics.md). The rule above is the obligation surface; the mechanics file is the catalog.

package/.agent-src/rules/improve-before-implement.md

@@ -4,6 +4,15 @@ tier: "2b"
 description: "Before implementing features or architectural changes — validate the request against existing code, challenge weak requirements, and suggest improvements"
 alwaysApply: false
 source: package
+council_depth: deep
+triggers:
+  - intent: "implement feature"
+  - intent: "architectural change"
+  - keyword: "refactor"
+validator_ignore:
+  - type: "substring"
+    pattern: ".agent-src.uncompressed/"
+    reason: "Rule cites the authoring tree when describing where examples live."
 ---
 
 # Improve Before Implement
@@ -42,10 +51,10 @@ Before coding, quickly verify:
 - Does it follow established patterns in the codebase?
 - Does it contradict existing conventions?
 - Do **multiple valid patterns/frameworks** already exist (e.g. Tailwind + Flux, multiple form libraries, competing state stores)? If yes, do NOT pick one arbitrarily — ask which to use.
-- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`docs/guidelines/php/patterns/strategy.md`](../../docs/guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
+- Is the change a **second branch on the same discriminator** — second `match`/`switch` arm, second `if/elseif`, or second class hardcoded to one enum value (e.g. `Provider::FOO`, `'stripe'`)? If yes, run the Strategy sniff test before adding the branch — see [`docs/guidelines/php/patterns/strategy.md`](../docs/guidelines/php/patterns/strategy.md#sniff-test--when-an-enumstring-discriminator-wants-to-become-a-strategy).
 
 **If misfit** → show evidence (file references), propose alternative.
-**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
+**If multiple valid options** → list them, ask which to use. See [`no blind implementation`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md#2-no-blind-implementation).
 
 ### 3. Is the approach sound?
 

package/.agent-src/rules/invite-challenge.md

@@ -0,0 +1,71 @@
+---
+type: "auto"
+tier: "2b"
+description: "Before executing a complex plan or non-trivial design — proactively ask 'am I solving the right problem?' and pause for user confirmation, even when no ambiguity is detected"
+alwaysApply: false
+source: package
+council_depth: deep
+triggers:
+  - intent: "complex plan"
+  - intent: "design decision"
+  - intent: "architectural plan"
+  - intent: "multi-step implementation"
+  - keyword: "plan"
+  - keyword: "design"
+  - keyword: "architecture"
+  - keyword: "approach"
+---
+
+# invite-challenge
+
+## The Iron Law
+
+```
+BEFORE EXECUTING A COMPLEX PLAN — ASK ONCE:
+"AM I SOLVING THE RIGHT PROBLEM?"
+PAUSE. WAIT FOR CONFIRMATION. THEN PROCEED.
+```
+
+Proactive confirmation checkpoint. Distinct from [`direct-answers`](direct-answers.md) (reactive — fires after misdirection is detected) and [`ask-when-uncertain`](ask-when-uncertain.md) (info-gathering — fires when context is missing). This rule fires when context is **sufficient** and direction **looks correct** but the plan is heavy enough that a silent misread would be expensive.
+
+## When to activate
+
+Two or more of:
+
+- Touches ≥ 3 files or ≥ 2 modules
+- New abstraction, pattern, or library
+- Security / billing / tenant / data-boundary path
+- Migration, schema change, or backwards-incompatible API change
+- Estimated effort > 30 min of agent work
+- High-level goal ("rebuild the dashboard") rather than a bounded task ("rename this method")
+
+**Does NOT activate for:** evidenced bug fixes · trivial edits · user-fenced tasks ("just do it") · steps inside an already-confirmed plan (ask once per plan, not per step) · cases handled by [`improve-before-implement`](improve-before-implement.md) Phase 1.
+
+## How to challenge
+
+One question, one turn. Numbered options per [`user-interaction`](user-interaction.md):
+
+```
+> Before I start, one check:
+>
+> Goal as I read it: {1-sentence restatement}
+> Plan: {2-3 bullet shape, not full implementation}
+> Risk if I misread: {what would be wasted}
+>
+> 1. Goal + plan match — proceed
+> 2. Goal right, plan needs adjustment — say what
+> 3. Goal wrong — let me restate
+```
+
+The restatement is the load-bearing part. Pick 1 → execute. Pick 2 or 3 → fold the correction in, do not re-ask.
+
+## Scope limits
+
+- **One challenge per plan**, not per step.
+- **Skip when the user already restated the goal** in the same turn.
+- **Skip when [`scope-control § fenced step`](scope-control.md) applies** — deliver the plan, hand back, no confirmation question appended.
+- **Never argue the goal twice** — user's restatement is final for the turn.
+
+## Interactions
+
+[`direct-answers`](direct-answers.md) fires after misdirection · [`ask-when-uncertain`](ask-when-uncertain.md) fires on missing context · [`improve-before-implement`](improve-before-implement.md) Phase 1 already runs a clarity check (do not double-ask) · [`scope-control § fenced step`](scope-control.md) handback wins · [`no-cheap-questions`](no-cheap-questions.md) — checkpoint must carry a real goal restatement, not a content-free "ready?".