@event4u/agent-config 1.28.0 → 1.31.0

package/CHANGELOG.md

@@ -318,6 +318,119 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.31.0](https://github.com/event4u-app/agent-config/compare/1.29.0...1.31.0) (2026-05-09)
+
+### Features
+
+* **chat-history:** cross-agent hardening — smoke isolation + multi-agent attribution ([b215b8f](https://github.com/event4u-app/agent-config/commit/b215b8f05bef439a95be9cc11c35d22f888696d1))
+* consolidate agent-doc commands into frequency-weighted surface ([9ce7476](https://github.com/event4u-app/agent-config/commit/9ce74764edfe2b6474311d3c8f01f3ac8018378c))
+* capability-over-structure for AGENTS.md (anatomy + linter + /optimize:agents-md) ([309042d](https://github.com/event4u-app/agent-config/commit/309042d8d15b3c13e9a70fe160d52208fe33ef98))
+* **release:** inject test-count trend into changelog footer ([3476186](https://github.com/event4u-app/agent-config/commit/347618644a658eda45003271f8da8b1c36097089))
+* **linter:** exempt cluster-head commands from no_steps; recognize ### Step N ([ad66bf0](https://github.com/event4u-app/agent-config/commit/ad66bf0001ef4acd2be662591b673e1e2822e83a))
+
+### Bug Fixes
+
+* **readme:** drop stale deprecation-shim sub-line; trim to 500-line cap ([5f92841](https://github.com/event4u-app/agent-config/commit/5f9284177323585ebb8b5fbca870f853c5c34ee0))
+* **check-portability:** allowlist agents-md-anatomy.md for task-invocation detector ([3301d19](https://github.com/event4u-app/agent-config/commit/3301d193ba55e95cdab47d8e3288a524ce7b8b90))
+* **ci:** sync compression hashes for governance + projection sections ([0fe814d](https://github.com/event4u-app/agent-config/commit/0fe814d7304ce8363b7a19e408fbb005aac67f05))
+* **skills:** close 4 linter warnings on Microck-harvested skills ([dda7a81](https://github.com/event4u-app/agent-config/commit/dda7a8181aee3f20b4ce9910d66e45db51aff9ba))
+
+### Documentation
+
+* **guidelines:** add universal code-clarity guideline (inline single-use values) ([d11b6cb](https://github.com/event4u-app/agent-config/commit/d11b6cbe6f6a31e7ed01e0b224365e6830e4b385))
+* **contributing:** add agent-assisted contribution workflow section ([0daf3b9](https://github.com/event4u-app/agent-config/commit/0daf3b9b89696780cb4c027fff7ce4be4dfa23a5))
+* **roadmap:** decouple roadmaps from merge / commit steps ([40a64a0](https://github.com/event4u-app/agent-config/commit/40a64a0a31b31c05ca7de05a1a7b267634a53c7b))
+* **roadmap:** close road-to-feedback-followups · agent-side complete ([efa4406](https://github.com/event4u-app/agent-config/commit/efa4406d4cc38cbcd3ebdb355c991da53d43a4c7))
+* **skills:** governance-baseline + Claude-skill projection notes ([f9306e1](https://github.com/event4u-app/agent-config/commit/f9306e1f53c1f7ce735ba039ae22a8a0ebcc05b6))
+
+### Refactoring
+
+* **skills:** rename repomix → repomix-packer ([62eec15](https://github.com/event4u-app/agent-config/commit/62eec153f770ebf848f1dcf84b30c036001a63ef))
+
+### Chores
+
+* regenerate agents/index.md (drop stale copilot-agents shim row) ([fa9ca32](https://github.com/event4u-app/agent-config/commit/fa9ca323952b31a7a85177dca65c46a31dd0e931))
+* **roadmap:** set archived chat-history roadmap status to LANDED ([a42f7a8](https://github.com/event4u-app/agent-config/commit/a42f7a86b6d49dc20f87e577574512a4c7fb5c00))
+* **roadmap:** close chat-history-cross-agent-hardening ([5129c33](https://github.com/event4u-app/agent-config/commit/5129c3336bc647925ff3abb00344272b37b98433))
+* retire /copilot-agents shim and clean up references ([295e3aa](https://github.com/event4u-app/agent-config/commit/295e3aa6f683263b9f5a8451bb94cb7468bfd00d))
+* canonicalize Known False Positives section in copilot-instructions.md ([c1a20bd](https://github.com/event4u-app/agent-config/commit/c1a20bd474895974f442bc5d2545175d39021e1e))
+* collapse editing-repo pointers in AGENTS.md to reclaim WARN headroom ([934800a](https://github.com/event4u-app/agent-config/commit/934800a6334e88494ffad37a3f5204e05bb60b1c))
+* archive completed road-to-agent-command-consolidation roadmap ([829704b](https://github.com/event4u-app/agent-config/commit/829704b797cd10b79ce0b70cc9d1b14cd3ce5664))
+* thin-root awareness for command-count gate; refresh doc counts ([6040c45](https://github.com/event4u-app/agent-config/commit/6040c4524ff84673adc8a403a2f6ab5e105b0af4))
+* regenerate compressed sources and tool projections ([0e83fb9](https://github.com/event4u-app/agent-config/commit/0e83fb9a008c6d083c8c2d1a53e645abe2b2541c))
+
+### Other
+
+* 1.30.0 ([ee26092](https://github.com/event4u-app/agent-config/commit/ee26092f161cd5d5486f8aa859156bc30fae54f2))
+
+Tests: 2486
+
+## [1.30.0](https://github.com/event4u-app/agent-config/compare/1.29.0...1.30.0) (2026-05-09)
+
+### Features
+
+* consolidate agent-doc commands into frequency-weighted surface ([9ce7476](https://github.com/event4u-app/agent-config/commit/9ce74764edfe2b6474311d3c8f01f3ac8018378c))
+* capability-over-structure for AGENTS.md (anatomy + linter + /optimize:agents-md) ([309042d](https://github.com/event4u-app/agent-config/commit/309042d8d15b3c13e9a70fe160d52208fe33ef98))
+* **release:** inject test-count trend into changelog footer ([3476186](https://github.com/event4u-app/agent-config/commit/347618644a658eda45003271f8da8b1c36097089))
+* **linter:** exempt cluster-head commands from no_steps; recognize ### Step N ([ad66bf0](https://github.com/event4u-app/agent-config/commit/ad66bf0001ef4acd2be662591b673e1e2822e83a))
+
+### Bug Fixes
+
+* **readme:** drop stale deprecation-shim sub-line; trim to 500-line cap ([5f92841](https://github.com/event4u-app/agent-config/commit/5f9284177323585ebb8b5fbca870f853c5c34ee0))
+* **check-portability:** allowlist agents-md-anatomy.md for task-invocation detector ([3301d19](https://github.com/event4u-app/agent-config/commit/3301d193ba55e95cdab47d8e3288a524ce7b8b90))
+* **ci:** sync compression hashes for governance + projection sections ([0fe814d](https://github.com/event4u-app/agent-config/commit/0fe814d7304ce8363b7a19e408fbb005aac67f05))
+* **skills:** close 4 linter warnings on Microck-harvested skills ([dda7a81](https://github.com/event4u-app/agent-config/commit/dda7a8181aee3f20b4ce9910d66e45db51aff9ba))
+
+### Documentation
+
+* **guidelines:** add universal code-clarity guideline (inline single-use values) ([d11b6cb](https://github.com/event4u-app/agent-config/commit/d11b6cbe6f6a31e7ed01e0b224365e6830e4b385))
+* **contributing:** add agent-assisted contribution workflow section ([0daf3b9](https://github.com/event4u-app/agent-config/commit/0daf3b9b89696780cb4c027fff7ce4be4dfa23a5))
+* **roadmap:** decouple roadmaps from merge / commit steps ([40a64a0](https://github.com/event4u-app/agent-config/commit/40a64a0a31b31c05ca7de05a1a7b267634a53c7b))
+* **roadmap:** close road-to-feedback-followups · agent-side complete ([efa4406](https://github.com/event4u-app/agent-config/commit/efa4406d4cc38cbcd3ebdb355c991da53d43a4c7))
+* **skills:** governance-baseline + Claude-skill projection notes ([f9306e1](https://github.com/event4u-app/agent-config/commit/f9306e1f53c1f7ce735ba039ae22a8a0ebcc05b6))
+
+### Refactoring
+
+* **skills:** rename repomix → repomix-packer ([62eec15](https://github.com/event4u-app/agent-config/commit/62eec153f770ebf848f1dcf84b30c036001a63ef))
+
+### Chores
+
+* retire /copilot-agents shim and clean up references ([295e3aa](https://github.com/event4u-app/agent-config/commit/295e3aa6f683263b9f5a8451bb94cb7468bfd00d))
+* canonicalize Known False Positives section in copilot-instructions.md ([c1a20bd](https://github.com/event4u-app/agent-config/commit/c1a20bd474895974f442bc5d2545175d39021e1e))
+* collapse editing-repo pointers in AGENTS.md to reclaim WARN headroom ([934800a](https://github.com/event4u-app/agent-config/commit/934800a6334e88494ffad37a3f5204e05bb60b1c))
+* archive completed road-to-agent-command-consolidation roadmap ([829704b](https://github.com/event4u-app/agent-config/commit/829704b797cd10b79ce0b70cc9d1b14cd3ce5664))
+* thin-root awareness for command-count gate; refresh doc counts ([6040c45](https://github.com/event4u-app/agent-config/commit/6040c4524ff84673adc8a403a2f6ab5e105b0af4))
+* regenerate compressed sources and tool projections ([0e83fb9](https://github.com/event4u-app/agent-config/commit/0e83fb9a008c6d083c8c2d1a53e645abe2b2541c))
+
+Tests: 2471
+
+## [1.29.0](https://github.com/event4u-app/agent-config/compare/1.28.0...1.29.0) (2026-05-09)
+
+### Features
+
+* **skills:** port 3 Microck skills under Sunset Policy (P2.2, P2.3, P2.5) ([78fdfeb](https://github.com/event4u-app/agent-config/commit/78fdfebf5f515e67072f9cb4a75ca7f56ca9b1b2))
+* **skills:** port error-handling-patterns from Microck under Sunset Policy (P1.5) ([c24589c](https://github.com/event4u-app/agent-config/commit/c24589c2c5e27e7182061660b98cca3d1e97fbae))
+* **skills:** port mcp-builder from Microck (P1.4) ([b192b38](https://github.com/event4u-app/agent-config/commit/b192b38c58245d7e8d33bdf5d577e41ba968cba5))
+* **skills:** port repomix from Microck (P1.3) ([825fd17](https://github.com/event4u-app/agent-config/commit/825fd175082b78fb2fd6250befb8cea86f1c3a0d))
+* **skills:** port testing-anti-patterns from Microck (P1.2) ([8bca47f](https://github.com/event4u-app/agent-config/commit/8bca47fab1db5811eada9bbb1f9545ebd1a68a4d))
+* **skills:** port defense-in-depth from Microck (P1.1) ([fb9bbb1](https://github.com/event4u-app/agent-config/commit/fb9bbb1e74890a63a1499a22ead0e79ab0a73ed6))
+
+### Bug Fixes
+
+* **refs:** point sibling roadmap link to archived microck-harvest ([92586a9](https://github.com/event4u-app/agent-config/commit/92586a9339e66b57121356ff644f2e3a706050e0))
+
+### Documentation
+
+* **microck-harvest:** record P2/P3 verdicts in provenance + analysis ([5200097](https://github.com/event4u-app/agent-config/commit/5200097a42bca40df03f4ecb232fea269ce6aacf))
+
+### Chores
+
+* **microck-harvest:** regenerate ownership matrix for 3 new skills ([855e331](https://github.com/event4u-app/agent-config/commit/855e3310729b0f359425c3c3e75541d98162cab4))
+* **microck-harvest:** regenerate index + catalog for 153 skills ([1d5f265](https://github.com/event4u-app/agent-config/commit/1d5f2654fbf2997a1465e965097eff8bce9f7ca2))
+* **roadmap:** close + archive microck-harvest (Phase 2 + 3 \u2014 100%) ([48c18f0](https://github.com/event4u-app/agent-config/commit/48c18f07a68342782d7d079e2371a613ee7a7c2e))
+* **microck-harvest:** register 3 new skills in marketplace + counts (150 \u2192 153) ([0e8b351](https://github.com/event4u-app/agent-config/commit/0e8b3518853add4b28e1e45f5babc550eaa974d1))
+* **microck-harvest:** suite integration + Phase 1 closure (P1.6) ([6450e9d](https://github.com/event4u-app/agent-config/commit/6450e9deea5806f4f8bfcddf12df9eeeae37c9cb))
+
 ## [1.28.0](https://github.com/event4u-app/agent-config/compare/1.27.0...1.28.0) (2026-05-09)
 
 ### Features

package/CONTRIBUTING.md

@@ -92,6 +92,96 @@ task lint-skills      # python3 scripts/skill_linter.py --all
   [`augment-portability`](.agent-src/rules/augment-portability.md) rule and
   `scripts/check_portability.py` enforce this in CI.
 
+## Agent-assisted contribution workflow
+
+The package is **maintenance-assisted** and **learning-supported** — not
+self-maintaining or self-learning. Automation handles structural quality
+and proposes changes; humans own semantic judgment and approve every
+change. The distinction matters: drafting a skill is fast, but
+generalizing it correctly and writing a trigger phrase that actually
+fires for the right intents still takes human review.
+
+### What the agent does for you
+
+Helper skills (`skill-writing`, `rule-writing`, `command-writing`,
+`description-assist`, `skill-reviewer`, `check-refs`,
+`agents-md-thin-root`) cover the mechanical work. You describe the
+intent — *"a skill that validates JWT tokens"*, *"a rule banning
+silent fallbacks"* — and the agent:
+
+- picks the right artefact type (skill vs. rule vs. command vs. guideline);
+- places it in the correct directory under `.agent-src.uncompressed/`;
+- writes frontmatter, trigger phrase (≤ 200 chars, multi-trigger coverage),
+  required sections, and a size budget that fits the linter;
+- runs `task sync` so the compressed and projected copies stay aligned;
+- runs `task lint-skills` and `task ci` and proposes fixes for any
+  failures.
+
+You do not need to memorise the directory layout, the kernel-rule budget,
+the size enforcement table, or the compression-hash registry. You do
+need to know *what* you want, *why* it generalises beyond your project,
+and *when* the agent's draft is wrong.
+
+### What CI catches and what it does not
+
+CI is structural, not semantic. `task ci` enforces frontmatter shape,
+description length, size budgets, compression-hash drift, broken
+cross-references, missing language anchors, kernel-rule prominence, and
+roadmap-dashboard sync. It will reject a malformed skill before review.
+
+CI cannot tell you whether a trigger phrase actually fires when it
+should, whether an example generalises beyond your project, or whether
+a new rule contradicts an existing one in spirit. That judgment is
+yours. Plan on one or two CI feedback rounds on a first contribution —
+this is normal, not a sign the docs lied.
+
+### Learning from real use — what it actually means
+
+The `learning-to-rule-or-skill` skill, the `capture-learnings` rule,
+and the `skill-improvement-pipeline` together let the agent **propose**
+rules or skills based on patterns it observed during a task. They never
+auto-promote anything. Every proposal lands as a draft for you to
+accept, reword, or discard. There is no cross-project training loop —
+each consumer project's learnings stay local unless you explicitly opt
+in to upstream contribution.
+
+Toggle: `pipelines.skill_improvement: true` in `.agent-settings.yml`
+(default true; set false for a silent agent).
+
+### Optional upstream contribution
+
+A consumer project can opt in to feed learnings back as PRs against
+this repository. Set `project.upstream_repo: "event4u-app/agent-config"`
+in `.agent-settings.yml` (empty by default). With it set, the
+`upstream-contribute` skill and `upstream-proposal` rule become active
+and the agent may **propose** an upstream PR when a local learning
+generalises.
+
+The setting flip is the easy part. Before enabling it, confirm:
+
+- **You have the right to contribute.** Check your employment contract
+  and your company's IP / open-source policy. Code and prose written
+  during work hours often belong to your employer.
+- **No proprietary content leaks.** Generalisation must strip internal
+  API names, customer identifiers, secrets, and project-specific
+  domain language. The agent assists; you verify.
+- **MIT license is acceptable.** Contributions ship under the package's
+  [MIT License](LICENSE).
+- **You review every PR before submission.** The skill's Iron Law is
+  *never create a PR without explicit user consent*. Setting the config
+  is not consent — clicking through the proposal is.
+
+### Honest limits
+
+- The agent drafts; you decide. *"It compiled, ship it"* is not a
+  review.
+- A structurally clean skill can still be semantically useless. Read
+  the trigger phrase out loud and ask whether you would actually want
+  the skill to fire on those words.
+- The package improves when contributors push back on the agent's
+  drafts. Silent acceptance is the failure mode that produces noisy,
+  redundant, or misfiring rules.
+
 ## Installer and Python tooling
 
 - Primary installer entry point: `scripts/install` (bash orchestrator).

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>145 Skills</strong> · <strong>60 Rules</strong> · <strong>104 Commands</strong> · <strong>62 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>153 Skills</strong> · <strong>60 Rules</strong> · <strong>101 Commands</strong> · <strong>63 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -343,7 +343,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
 | [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
 
-→ [Browse all 104 active commands](.agent-src/commands/)
+→ [Browse all 101 active commands](.agent-src/commands/)
 
 ---
 
@@ -368,7 +368,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 145 skills + 104 native commands). Cursor, Cline, Windsurf,
+> package (rules + 153 skills + 101 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/docs/architecture.md

@@ -96,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 145 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 153 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 104 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 62 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Commands** | 101 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 63 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **368 public artefacts** shipped by
+Consumer-facing catalog of all **374 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (145)
+## Skills (153)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -22,6 +22,7 @@ are excluded.
 | skill | [`api-endpoint`](../.agent-src/skills/api-endpoint/SKILL.md) |  | Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs. |
 | skill | [`api-testing`](../.agent-src/skills/api-testing/SKILL.md) |  | Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing. |
 | skill | [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) |  | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
+| skill | [`async-python-patterns`](../.agent-src/skills/async-python-patterns/SKILL.md) |  | Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized. |
 | skill | [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) |  | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
 | skill | [`aws-infrastructure`](../.agent-src/skills/aws-infrastructure/SKILL.md) |  | Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS. |
 | skill | [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) |  | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
@@ -43,6 +44,7 @@ are excluded.
 | skill | [`database`](../.agent-src/skills/database/SKILL.md) |  | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
 | skill | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) |  | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
 | skill | [`deep-reading-analyst`](../.agent-src/skills/deep-reading-analyst/SKILL.md) |  | Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary. |
+| skill | [`defense-in-depth`](../.agent-src/skills/defense-in-depth/SKILL.md) |  | Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one. |
 | skill | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) |  | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
 | skill | [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) |  | Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'. |
 | skill | [`design-review`](../.agent-src/skills/design-review/SKILL.md) |  | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
@@ -51,6 +53,7 @@ are excluded.
 | skill | [`docker`](../.agent-src/skills/docker/SKILL.md) |  | Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'. |
 | skill | [`dto-creator`](../.agent-src/skills/dto-creator/SKILL.md) |  | Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping. |
 | skill | [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) |  | Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions. |
+| skill | [`error-handling-patterns`](../.agent-src/skills/error-handling-patterns/SKILL.md) |  | Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized. |
 | skill | [`estimate-ticket`](../.agent-src/skills/estimate-ticket/SKILL.md) |  | Estimate a Jira/Linear ticket — 'estimate PROJ-123', 'wie groß ist das?', 'should we split this?' — size + risk + split + uncertainty, sibling of /refine-ticket, close-prompt. |
 | skill | [`existing-ui-audit`](../.agent-src/skills/existing-ui-audit/SKILL.md) |  | Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set. |
 | skill | [`fe-design`](../.agent-src/skills/fe-design/SKILL.md) |  | Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py. |
@@ -85,6 +88,7 @@ are excluded.
 | skill | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) |  | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
 | skill | [`markitdown`](../.agent-src/skills/markitdown/SKILL.md) |  | Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'. |
 | skill | [`mcp`](../.agent-src/skills/mcp/SKILL.md) |  | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
+| skill | [`mcp-builder`](../.agent-src/skills/mcp-builder/SKILL.md) |  | Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness. |
 | skill | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) |  | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |
 | skill | [`merge-conflicts`](../.agent-src/skills/merge-conflicts/SKILL.md) |  | Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow. |
 | skill | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) |  | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
@@ -112,6 +116,7 @@ are excluded.
 | skill | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) |  | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
 | skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
+| skill | [`prompt-engineering-patterns`](../.agent-src/skills/prompt-engineering-patterns/SKILL.md) |  | Use when designing production-LLM prompts — few-shot, chain-of-thought, system prompts, templates, self-verification — distinct from prompt-optimizer and refine-prompt. |
 | skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
 | skill | [`react-native-setup`](../.agent-src/skills/react-native-setup/SKILL.md) |  | Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'. |
@@ -122,6 +127,7 @@ are excluded.
 | skill | [`receiving-code-review`](../.agent-src/skills/receiving-code-review/SKILL.md) |  | Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'. |
 | skill | [`refine-prompt`](../.agent-src/skills/refine-prompt/SKILL.md) |  | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'. |
 | skill | [`refine-ticket`](../.agent-src/skills/refine-ticket/SKILL.md) |  | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
+| skill | [`repomix-packer`](../.agent-src/skills/repomix-packer/SKILL.md) |  | Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI. |
 | skill | [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) |  | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
 | skill | [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) |  | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
 | skill | [`rice-prioritization`](../.agent-src/skills/rice-prioritization/SKILL.md) |  | Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort. |
@@ -130,6 +136,7 @@ are excluded.
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
 | skill | [`script-writing`](../.agent-src/skills/script-writing/SKILL.md) |  | Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'. |
+| skill | [`secrets-management`](../.agent-src/skills/secrets-management/SKILL.md) |  | Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized. |
 | skill | [`security`](../.agent-src/skills/security/SKILL.md) |  | Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding. |
 | skill | [`security-audit`](../.agent-src/skills/security-audit/SKILL.md) |  | ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work. |
 | skill | [`sentry-integration`](../.agent-src/skills/sentry-integration/SKILL.md) |  | Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis. |
@@ -146,6 +153,7 @@ are excluded.
 | skill | [`terragrunt`](../.agent-src/skills/terragrunt/SKILL.md) |  | 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. |
 | skill | [`test-driven-development`](../.agent-src/skills/test-driven-development/SKILL.md) |  | 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'. |
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
+| skill | [`testing-anti-patterns`](../.agent-src/skills/testing-anti-patterns/SKILL.md) |  | Use BEFORE writing or changing tests, adding mocks, or putting test-only methods on production classes — five Iron Laws and gates against mocking-the-mock, production pollution, silent partial mocks. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
 | skill | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) |  | Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
@@ -219,16 +227,16 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (104)
+## Commands (101)
 
 | kind | name | cluster | description |
 |---|---|---|---|
 | command | [`agent-handoff`](../.agent-src/commands/agent-handoff.md) |  | Generate a context summary for continuing work in a fresh chat. Replaces the session system. |
 | command | [`agent-status`](../.agent-src/commands/agent-status.md) |  | Show current conversation stats — message count, token costs, task progress, next freshness check. |
-| command | [`agents:audit`](../.agent-src/commands/agents/audit.md) | cluster: agents | Audits agents/ and module agents/ directories — finds outdated docs, structural issues, duplicates, orphaned overrides, and creates an improvement roadmap. |
-| command | [`agents:cleanup`](../.agent-src/commands/agents/cleanup.md) | cluster: agents | Execute cleanup actions from an agents-audit — move, merge, delete, and update agent docs |
-| command | [`agents:prepare`](../.agent-src/commands/agents/prepare.md) | cluster: agents | Scaffold the agents/ directory structure with all required subdirectories and .gitkeep files |
-| command | [`agents`](../.agent-src/commands/agents.md) | cluster: agents | Agents-folder orchestrator — routes to audit, cleanup, prepare |
+| command | [`agents:audit`](../.agent-src/commands/agents/audit.md) | cluster: agents | Audit agent infrastructure — token overhead, rule triggers, AGENTS.md health, Capability-over-Structure adherence, stale references. Read-only, suggest-only, never auto-apply. |
+| command | [`agents:init`](../.agent-src/commands/agents/init.md) | cluster: agents | Initialize the agent layer for a consumer project — creates AGENTS.md and .github/copilot-instructions.md from package templates, auto-detects stack, never leaks other projects' identifiers. |
+| command | [`agents:optimize`](../.agent-src/commands/agents/optimize.md) | cluster: agents | Refactor AGENTS.md to the Thin-Root contract (caps, pointer ratio, capability bullets, emergency-triage) and propagate to tool stubs. Suggest only, never auto-apply. |
+| command | [`agents`](../.agent-src/commands/agents.md) | cluster: agents | Agent-layer orchestrator — routes to init, optimize, audit. Covers AGENTS.md and its multi-tool stubs (CLAUDE.md, GEMINI.md, copilot-instructions.md, .cursorrules). |
 | command | [`analyze-reference-repo`](../.agent-src/commands/analyze-reference-repo.md) |  | Analyze an external reference repository (competitor, inspiration, peer) and produce a structured comparison + adoption plan for this project. |
 | command | [`bug-fix`](../.agent-src/commands/bug-fix.md) |  | Plan and implement a bug fix — based on investigation, with quality checks and test verification |
 | command | [`bug-investigate`](../.agent-src/commands/bug-investigate.md) |  | Investigate a bug — auto-detect ticket from branch, gather Jira/Sentry/description context, trace root cause |
@@ -246,9 +254,6 @@ are excluded.
 | command | [`context:create`](../.agent-src/commands/context/create.md) | cluster: context | Analyze a codebase area and create a structured context document |
 | command | [`context:refactor`](../.agent-src/commands/context/refactor.md) | cluster: context | Analyze, update, and extend an existing context document |
 | command | [`context`](../.agent-src/commands/context.md) | cluster: context | Context orchestrator — routes to create, refactor |
-| command | [`copilot-agents:init`](../.agent-src/commands/copilot-agents/init.md) | cluster: copilot-agents | Create AGENTS.md and .github/copilot-instructions.md from scratch in the consumer project — interactive, auto-detects stack, never leaks other projects' identifiers. |
-| command | [`copilot-agents:optimize`](../.agent-src/commands/copilot-agents/optimize.md) | cluster: copilot-agents | Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience. |
-| command | [`copilot-agents`](../.agent-src/commands/copilot-agents.md) | cluster: copilot-agents | Copilot agents-doc orchestrator — routes to init, optimize |
 | command | [`cost-report`](../.agent-src/commands/cost-report.md) |  | Capture token cost from the active Claude Code session, append to the local sessions store, and surface the 50/75/90/100% budget alert ladder with cost-profile suggestions. |
 | command | [`council:default`](../.agent-src/commands/council/default.md) | cluster: council | Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare. |
 | command | [`council:design`](../.agent-src/commands/council/design.md) | cluster: council | Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment. |
@@ -291,12 +296,12 @@ are excluded.
 | command | [`module:explore`](../.agent-src/commands/module/explore.md) | cluster: module | Explore a module — load its structure, docs, and context into the current conversation |
 | command | [`module`](../.agent-src/commands/module.md) | cluster: module | Module orchestrator — routes to create, explore |
 | command | [`onboard`](../.agent-src/commands/onboard.md) |  | First-run setup for a developer on this project — captures name, IDE, bot-icon preference, rtk, cost_profile, and learning opt-out, then sets onboarding.onboarded=true |
-| command | [`optimize:agents`](../.agent-src/commands/optimize/agents.md) | cluster: optimize | Audits agent infrastructure — measures token overhead, checks rule triggers, verifies AGENTS.md. Suggest only, never auto-apply. |
+| command | [`optimize:agents-dir`](../.agent-src/commands/optimize/agents-dir.md) | cluster: optimize | Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / --audit / --fix); default = interactive wizard. |
 | command | [`optimize:augmentignore`](../.agent-src/commands/optimize/augmentignore.md) | cluster: optimize | Creates or updates .augmentignore based on the project's actual tech stack, large files, generated artifacts, and irrelevant agent skills/rules. |
 | command | [`optimize:rtk`](../.agent-src/commands/optimize/rtk.md) | cluster: optimize | Create or optimize project-local rtk filters based on the actual toolchain |
 | command | [`optimize:skills`](../.agent-src/commands/optimize/skills.md) | cluster: optimize | Audits skills — measures baseline, finds duplicates/merge candidates, runs linter. Suggest only, never auto-apply. |
 | command | [`optimize-prompt`](../.agent-src/commands/optimize-prompt.md) | cluster: optimize | Optimize a raw prompt for ChatGPT, Claude, Gemini, or another AI via the 4-D methodology — BASIC vs DETAIL auto-detect, one clarifying question per turn, returns the polished prompt. |
-| command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters |
+| command | [`optimize`](../.agent-src/commands/optimize.md) | cluster: optimize | Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters |
 | command | [`override:create`](../.agent-src/commands/override/create.md) | cluster: override | Creates a project-level override for a shared skill, rule, or command. |
 | command | [`override:manage`](../.agent-src/commands/override/manage.md) | cluster: override | Reviews, updates, and refactors existing project-level overrides. |
 | command | [`override`](../.agent-src/commands/override.md) | cluster: override | Override orchestrator — routes to create, manage |
@@ -328,7 +333,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (62)
+## Guidelines (63)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -362,6 +367,7 @@ are excluded.
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
 | guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
 | guideline | [`augment-portability-patterns`](../docs/guidelines/augment-portability-patterns.md) | (root) |  |
+| guideline | [`code-clarity`](../docs/guidelines/code-clarity.md) | (root) |  |
 | guideline | [`readme-size-and-splitting`](../docs/guidelines/docs/readme-size-and-splitting.md) | docs |  |
 | guideline | [`playwright`](../docs/guidelines/e2e/playwright.md) | e2e |  |
 | guideline | [`api-design`](../docs/guidelines/php/api-design.md) | php |  |

package/docs/contracts/command-clusters.md

@@ -28,17 +28,16 @@ column 1 of this table.
 | Cluster | Phase | Sub-commands | Replaces |
 |---|:-:|---|---|
 | `fix` | 1 | `ci` · `pr` · `pr-bots` · `pr-developers` · `portability` · `refs` · `seeder` | `fix-ci` · `fix-pr-comments` · `fix-pr-bot-comments` · `fix-pr-developer-comments` · `fix-portability` · `fix-references` · `fix-seeder` |
-| `optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `optimize-agents` · `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` |
+| `optimize` | 1 | `agents-dir` · `augmentignore` · `rtk` · `skills` | `optimize-augmentignore` · `optimize-rtk-filters` · `optimize-skills` · former `/optimize agents` and `/optimize agents-md` moved to the `/agents` file-family cluster 2026-05-09; `/agents prepare/audit/cleanup` collapsed into the single `/optimize agents-dir` (flags or wizard) per the agent-doc consolidation |
 | `feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` · `dev` | `feature-explore` · `feature-plan` · `feature-refactor` · `feature-roadmap` · `feature-dev` |
 | `chat-history` | 2 | `show` · `import` · `learn` | `chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only` (auto-adopt + structural hooks); `import` (verbatim cross-session render) and `learn` (project-improving learning extraction) added in the v4 stateless schema |
-| `agents` | 2 | `audit` · `cleanup` · `prepare` | `agents-audit` · `agents-cleanup` · `agents-prepare` |
+| `agents` | 2 | `init` · `optimize` · `audit` | AGENTS.md file family (high-frequency) — repurposed 2026-05-09: `init` (was `/copilot-agents init`) · `optimize` (merger of `/optimize agents-md` + `/copilot-agents optimize`) · `audit` (was `/optimize agents`, collapses old `audit` + `check` verbs); legacy folder ops (`prepare` / `cleanup` / folder-`audit`) moved to `/optimize agents-dir` |
 | `memory` | 2 | `add` · `load` · `promote` · `propose` | `memory-add` · `memory-full` · `memory-promote` · `propose-memory` |
 | `roadmap` | 2 | `create` · `ai-council` · `process-step` · `process-phase` · `process-full` | `roadmap-create` · `roadmap-execute` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope); `ai-council` added 2026-05-07 — wraps `/council default` with `--input-mode roadmap --depth deep` |
 | `module` | 2 | `create` · `explore` | `module-create` · `module-explore` |
 | `tests` | 2 | `create` · `execute` | `tests-create` · `tests-execute` |
 | `context` | 2 | `create` · `refactor` | `context-create` · `context-refactor` |
 | `override` | 2 | `create` · `manage` | `override-create` · `override-manage` |
-| `copilot-agents` | 2 | `init` · `optimize` | `copilot-agents-init` · `copilot-agents-optimize` |
 | `judge` | 2 | `solo` · `on-diff` · `steps` | `judge` (legacy standalone) · `do-and-judge` · `do-in-steps` |
 | `commit` | 2 | `in-chunks` | `commit-in-chunks` |
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
@@ -149,6 +148,24 @@ the removal explicitly. The 1.17.0 release ships Phase 2 cluster
 locks **and** drops the seven Phase 1 atomic shims at the end of
 their deprecation cycle.
 
+## Agent-doc consolidation (2026-05-09)
+
+Single-release breaking change folding seven scattered agent-doc
+commands into the `/agents` (file-family) and `/optimize agents-dir`
+surfaces. Frequency-weighted: high-use AGENTS.md operations get the
+short `/agents` namespace; low-use folder ops nest under `/optimize`.
+
+| Old command | New command | Note |
+|---|---|---|
+| `/optimize agents-md` | `/agents optimize` | Thin-Root refactor folded into `/agents` |
+| `/optimize agents` | `/agents audit` | read-only audit folded into `/agents`; `audit` + `check` collapsed |
+| `/agents prepare` | `/optimize agents-dir` | `--scaffold` flag or wizard mode |
+| `/agents audit` (folder) | `/optimize agents-dir` | `--audit` flag |
+| `/agents cleanup` | `/optimize agents-dir` | `--fix` flag |
+
+Cluster `/copilot-agents` is retired; the file-family operations now
+live under `/agents` (`init`, `optimize`).
+
 ## Linter behavior
 
 `scripts/lint_no_new_atomic_commands.py`: