@event4u/agent-config 1.29.0 → 1.31.0

package/docs/contracts/file-ownership-matrix.json

@@ -27,13 +27,13 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/agents/cleanup.md": {
+    ".agent-src.uncompressed/commands/agents/init.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/agents/prepare.md": {
+    ".agent-src.uncompressed/commands/agents/optimize.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
@@ -141,24 +141,6 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/copilot-agents.md": {
-      "kind": "command",
-      "rule_type": null,
-      "load_context": [],
-      "load_context_eager": []
-    },
-    ".agent-src.uncompressed/commands/copilot-agents/init.md": {
-      "kind": "command",
-      "rule_type": null,
-      "load_context": [],
-      "load_context_eager": []
-    },
-    ".agent-src.uncompressed/commands/copilot-agents/optimize.md": {
-      "kind": "command",
-      "rule_type": null,
-      "load_context": [],
-      "load_context_eager": []
-    },
     ".agent-src.uncompressed/commands/cost-report.md": {
       "kind": "command",
       "rule_type": null,
@@ -423,7 +405,7 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/optimize/agents.md": {
+    ".agent-src.uncompressed/commands/optimize/agents-dir.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
@@ -699,6 +681,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md": {
+      "kind": "context",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md": {
       "kind": "context",
       "rule_type": null,
@@ -1938,7 +1926,7 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/skills/repomix/SKILL.md": {
+    ".agent-src.uncompressed/skills/repomix-packer/SKILL.md": {
       "kind": "skill",
       "rule_type": null,
       "load_context": [],
@@ -2183,6 +2171,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/agents.md",
+      "target": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/agents/audit.md",
       "target": ".agent-src.uncompressed/commands/agents/audit.md",
@@ -2191,19 +2186,110 @@
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/agents/cleanup.md",
-      "target": ".agent-src.uncompressed/commands/agents/cleanup.md",
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/rules/commit-policy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/rules/rule-type-governance.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/audit.md",
+      "target": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/init.md",
+      "target": ".agent-src.uncompressed/commands/agents/init.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/agents/prepare.md",
-      "target": ".agent-src.uncompressed/commands/agents/prepare.md",
+      "source": ".agent-src.uncompressed/commands/agents/init.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/commands/agents/optimize.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/emergency-triage-block.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/rules/commit-policy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/rules/scope-control.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/rules/verify-before-complete.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "target": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/analyze-reference-repo.md",
       "target": ".agent-src.uncompressed/commands/analyze-reference-repo.md",
@@ -2533,27 +2619,6 @@
       "via": "self",
       "depth": 0
     },
-    {
-      "source": ".agent-src.uncompressed/commands/copilot-agents.md",
-      "target": ".agent-src.uncompressed/commands/copilot-agents.md",
-      "type": "WRITE",
-      "via": "self",
-      "depth": 0
-    },
-    {
-      "source": ".agent-src.uncompressed/commands/copilot-agents/init.md",
-      "target": ".agent-src.uncompressed/commands/copilot-agents/init.md",
-      "type": "WRITE",
-      "via": "self",
-      "depth": 0
-    },
-    {
-      "source": ".agent-src.uncompressed/commands/copilot-agents/optimize.md",
-      "target": ".agent-src.uncompressed/commands/copilot-agents/optimize.md",
-      "type": "WRITE",
-      "via": "self",
-      "depth": 0
-    },
     {
       "source": ".agent-src.uncompressed/commands/cost-report.md",
       "target": ".agent-src.uncompressed/commands/agent-status.md",
@@ -3058,6 +3123,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize.md",
+      "target": ".agent-src.uncompressed/commands/agents.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/optimize.md",
       "target": ".agent-src.uncompressed/commands/optimize.md",
@@ -3066,12 +3138,54 @@
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/optimize/agents.md",
-      "target": ".agent-src.uncompressed/commands/optimize/agents.md",
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/commands/agents.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/commands/agents/audit.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/commands/agents/optimize.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/rules/commit-policy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/skills/agent-docs-writing/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/optimize/agents-dir.md",
+      "target": ".agent-src.uncompressed/skills/override-management/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/optimize/augmentignore.md",
       "target": ".agent-src.uncompressed/commands/optimize/augmentignore.md",
@@ -3961,6 +4075,34 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/consumer-agents-md-guide.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/emergency-triage-block.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "target": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md",
       "target": ".agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md",
@@ -5606,6 +5748,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/agents-md-anatomy.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
       "target": ".agent-src.uncompressed/rules/size-enforcement.md",
@@ -7364,43 +7513,43 @@
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "target": ".agent-src.uncompressed/commands/analyze-reference-repo.md",
       "type": "READ_ONLY",
       "via": "body_link",
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "target": ".agent-src.uncompressed/skills/blast-radius-analyzer/SKILL.md",
       "type": "READ_ONLY",
       "via": "body_link",
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "target": ".agent-src.uncompressed/skills/judge-bug-hunter/SKILL.md",
       "type": "READ_ONLY",
       "via": "body_link",
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "target": ".agent-src.uncompressed/skills/judge-security-auditor/SKILL.md",
       "type": "READ_ONLY",
       "via": "body_link",
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "target": ".agent-src.uncompressed/skills/markitdown/SKILL.md",
       "type": "READ_ONLY",
       "via": "body_link",
       "depth": 1
     },
     {
-      "source": ".agent-src.uncompressed/skills/repomix/SKILL.md",
-      "target": ".agent-src.uncompressed/skills/repomix/SKILL.md",
+      "source": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
+      "target": ".agent-src.uncompressed/skills/repomix-packer/SKILL.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0

package/docs/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 104 active commands](../.agent-src/commands/)
+→ [Browse all 101 active commands](../.agent-src/commands/)
 
 ---
 

package/docs/guidelines/code-clarity.md

@@ -0,0 +1,95 @@
+# Code Clarity
+
+> Cross-language coding-clarity conventions. Cited by language-specific
+> guidelines (`php/general.md`, `php/php-coding-patterns.md`, …) so
+> consumers in any stack get the same baseline.
+
+Applies to PHP, JavaScript / TypeScript, Python, Go, Ruby, and any
+other language the package guides. Language-specific files reference
+this one — they don't duplicate it.
+
+## Don't assign single-use values to a variable
+
+If a value is used **exactly once**, pass the expression directly.
+Don't bind it to a temporary variable just to feed it into the next
+call.
+
+The named variable buys nothing — it adds a line, an identifier the
+reader has to track, and a false signal that the value will be reused.
+
+```php
+// ❌ Avoid — $db is referenced exactly once.
+$db = db::getInstance();
+$this->columnExists($db, 'table', 'column');
+
+// ✅ Prefer — value flows directly to the call.
+$this->columnExists(db::getInstance(), 'table', 'column');
+```
+
+```ts
+// ❌ Avoid
+const user = await getCurrentUser();
+return renderProfile(user);
+
+// ✅ Prefer
+return renderProfile(await getCurrentUser());
+```
+
+```python
+# ❌ Avoid
+config = load_config()
+return Worker(config)
+
+# ✅ Prefer
+return Worker(load_config())
+```
+
+## Carve-outs — keep the variable when
+
+The rule is "single use, no extra meaning". Bind to a variable when
+**any** of these hold:
+
+| Carve-out | Why |
+|---|---|
+| **Used 2 or more times** | Inlining duplicates the expression — re-evaluation, repeated side effects, more diff churn. |
+| **Expression has side effects** | A network call, a write, an `INSERT`, a counter bump must run exactly once and be visible to the reader as such. |
+| **The name carries domain meaning** | `$activeMembership = …; allow($activeMembership)` — the identifier documents intent the call site can't. |
+| **Inlining pushes past the line-length budget** | A 130-char single line is harder to read than two named lines. Match the project's formatter. |
+| **Used inside a loop body** | Hoist the invariant out of the loop; keep the binding. |
+| **Debugger / breakpoint affordance** | Stepping through a named value is materially easier than inspecting an expression mid-call. Prefer the variable in code paths under active investigation. |
+| **Type-narrowing assertion** | `const x: Foo = maybeFoo!; …` where the binding pins the type for the type-checker. |
+
+When in doubt — and the expression is short, side-effect-free, and
+used once — inline it.
+
+## Why this matters
+
+- **Smaller diffs.** Two lines (`$x = ...; f($x)`) become one (`f(...)`)
+  — fewer review points, less merge conflict surface.
+- **Less cognitive load.** Readers don't track an identifier whose
+  whole purpose is "the next line".
+- **Honest signals.** A named variable says "this value is reusable
+  or worth labeling". Single-use bindings break that contract and
+  train readers to ignore names.
+- **Faster refactor.** Renaming the call site doesn't drag a now-stale
+  variable name with it.
+
+## Anti-patterns this rule rejects
+
+- **"Variable for the debugger."** If the file is not under active
+  debugging, drop the binding. Don't ship debug scaffolding.
+- **"Variable to align line lengths."** Use the formatter, not a
+  fake intermediate.
+- **"Variable so I have somewhere to put the type."** Modern type
+  inference makes this redundant in PHP 8+, TS, Python 3.10+, Go,
+  Rust, etc. Annotate the parameter or return type instead.
+
+## See also
+
+- Language-specific anchors that link to this guideline:
+  - PHP: `docs/guidelines/php/general.md` § Variables
+  - PHP: `docs/guidelines/php/php-coding-patterns.md` § Variables
+- `minimal-safe-diff` rule — orthogonal but aligned: smallest change
+  that solves the stated problem.
+- `direct-answers` rule — same spirit at the prose level: shortest
+  version that fully answers the question.

package/docs/guidelines/php/general.md

@@ -24,6 +24,14 @@
 - Retrieving: `getUser()`, `fetchUserData()` — not `user()`, `userData()`
 - Actions: `sendEmail()`, `processPayment()` — not `email()`, `payment()`
 
+## Variables
+
+- **Don't assign single-use values to a variable** — pass the expression
+  directly to the call. Universal rule with carve-outs (side effects,
+  loops, debugger, type narrowing) lives in
+  [`code-clarity.md`](../code-clarity.md) § Don't assign single-use
+  values to a variable.
+
 ## Strings
 
 - Single quotes when no interpolation: `$table = 'users';`

package/docs/guidelines/php/php-coding-patterns.md

@@ -15,6 +15,7 @@ _Origin: migrated from `.agent-src.uncompressed/rules/php-coding.md` per P4.2 of
 - No one-liner if statements.
 - Single quotes for strings without interpolation. `sprintf()` for complex strings.
 - Variables: `camelCase`. Array keys: `snake_case`. Constants: `UPPER_SNAKE_CASE`.
+- Don't assign single-use values to a variable — pass the expression directly. Carve-outs (side effects, loops, type narrowing) in [`code-clarity.md`](../code-clarity.md).
 - Typed properties, parameters, and return types — always.
 - Constructor property promotion where it makes sense.