@event4u/agent-config 1.29.0 → 1.32.0

package/CHANGELOG.md

@@ -318,6 +318,116 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.32.0](https://github.com/event4u-app/agent-config/compare/1.31.0...1.32.0) (2026-05-09)
+
+### Features
+
+* **roadmap:** bite-sized task granularity gate for structural roadmaps ([b23683d](https://github.com/event4u-app/agent-config/commit/b23683df15dd43229a25cad33882f6a692d92a97))
+* **skills:** add 3-scan self-review to planning skills ([6784fb8](https://github.com/event4u-app/agent-config/commit/6784fb8ad355ef5b2d7f2cebe5d5e26f114cbe4a))
+* **subagent-orchestration:** status taxonomy + externalized prompts + two-stage mode ([6d846a7](https://github.com/event4u-app/agent-config/commit/6d846a74441196b98cabf8cd1c18ca40db0cec89))
+* **skills:** TDD hardening with externalized anti-pattern catalogue ([db2b1a2](https://github.com/event4u-app/agent-config/commit/db2b1a2a550f10fa51742bef360044b9de1bb7ca))
+
+### Bug Fixes
+
+* **investigation:** inline council convergence (council files gitignored) ([ff93aa7](https://github.com/event4u-app/agent-config/commit/ff93aa7ee6f6cffff062838a644047470e1d462e))
+* **skills:** inline council convergence in anti-patterns provenance ([7d7e663](https://github.com/event4u-app/agent-config/commit/7d7e663f8e619882fd59465dfbfdb268132eeb8d))
+* **skills:** drop roadmap reference from anti-patterns provenance ([a49c010](https://github.com/event4u-app/agent-config/commit/a49c0107971a5b70a1fdf33ed1a19c91d075980a))
+
+### Chores
+
+* **ownership:** regenerate matrix after superpowers-harvest landing ([faf4794](https://github.com/event4u-app/agent-config/commit/faf479470db9c83d17e8332dd3498df1e5f4c34b))
+* **index:** regenerate after superpowers-harvest landing ([946f3cc](https://github.com/event4u-app/agent-config/commit/946f3ccad54da3a3898d0aeb4474be0b87e66800))
+* **roadmap:** remove old roadmap path (already archived) ([18f281b](https://github.com/event4u-app/agent-config/commit/18f281bbeb51e93feef40146af3a3b5e5cb916f2))
+* **roadmap:** close superpowers-harvest — Phase 1 LANDED, P1.4b deferred ([a296106](https://github.com/event4u-app/agent-config/commit/a296106c6a846a54c3fe20728203fb3bbae7fffc))
+
+Tests: 2560 (+74 since 1.31.0)
+
+## [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

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>153 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 + 153 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

@@ -98,8 +98,8 @@ fails on any source-side violation, without producing artifacts.
 |---|---|---|
 | **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,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **376 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.
 
@@ -127,7 +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`](../.agent-src/skills/repomix/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 | [`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. |
@@ -146,7 +146,7 @@ are excluded.
 | skill | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) |  | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | skill | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) |  | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
 | skill | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
-| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml. |
+| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
 | skill | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) |  | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
 | skill | [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) |  | Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure. |
 | skill | [`terraform`](../.agent-src/skills/terraform/SKILL.md) |  | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
@@ -227,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 |
@@ -254,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. |
@@ -299,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 |
@@ -336,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 |
 |---|---|---|---|
@@ -370,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`: