@event4u/agent-config 1.29.0 → 1.31.0

package/.agent-src/skills/rule-writing/SKILL.md

@@ -128,6 +128,27 @@ the PR or split by responsibility.
 * Run the full CI pipeline locally (see `Taskfile.yml` in this repo for
   the script list) — must exit 0 except for tolerated warnings.
 
+### 6. Governance baseline (when introducing a new linter check)
+
+**Advisory, reviewer-checked — no CI gate.** When the same PR adds a
+new check to `scripts/skill_linter.py` (or strengthens an existing one)
+such that previously-clean rules now warn, the PR body MUST record the
+pre-existing violations on `main` in a Markdown table:
+
+```markdown
+### Pre-existing baseline (informational)
+
+| Code | Count on main | Bucket |
+|---|---:|---|
+| {new_code} | N | (a) genuine fix · (b) accept · (c) check too aggressive |
+```
+
+Forward-only: the new check applies to **the rule under review** and to
+**future** edits. The baseline table is informational so reviewers can
+distinguish genuine debt from acceptable carry-overs without diffing the
+full lint output. See `agents/analysis/lint-warning-triage.md` for the
+3-bucket reference.
+
 ## Frontmatter shape
 
 ```yaml

package/.agent-src/skills/skill-writing/SKILL.md

@@ -59,6 +59,25 @@ Ask: **"Does the model need this to do its job correctly?"**
 * If the model knows it but does it wrong in THIS project → **Rule or Guideline**
 * If the model needs a multi-step workflow to get it right → **Skill**
 
+### Skills and commands share the `.claude/skills/` namespace
+
+Skills (`.agent-src.uncompressed/skills/{name}/SKILL.md`) AND commands
+(`.agent-src.uncompressed/commands/{name}.md`) both project into
+`.claude/skills/` (`scripts/compress.py` → `generate_claude_skills` +
+`generate_claude_commands`). Claude treats the directory as native
+skills.
+
+* Same-name collision: skill wins, command is skipped
+  (`generate_claude_commands` honors this). Don't reuse a command's
+  slug for a skill unless the command should retire.
+* Both compete on `description` for routing. A weak skill description
+  is shadowed by a stronger same-domain command — and vice versa.
+  Trigger phrasing must be precise (§ 1b below).
+* Workflow has both "user types `/foo`" path AND "model picks this up
+  from intent" path → author the skill first, let the command delegate
+  via `skills:` frontmatter. Two artifacts with the same trigger
+  surface fight each other in the router.
+
 ### When "Nothing" is the right answer
 
 Do NOT create a skill or rule for:

package/.agent-src/skills/testing-anti-patterns/SKILL.md

@@ -34,6 +34,10 @@ Do NOT use when:
 
 ## Procedure: Run the gate before each anti-pattern
 
+### 1. Inspect the diff before any new mock
+
+Before writing or extending a test, **inspect** the code under test and identify which collaborators are real, which are mocked, and which produce side effects the assertion depends on. Open the file, read the dependency chain, and write the chain down. Do not start mocking until the chain is on paper.
+
 ### Anti-Pattern 1 — Asserting on mock elements
 
 Symptom: `expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument()` or `$this->assertSee('mock-sidebar')`. Test passes when the mock is present, fails when it is not — proves nothing about the component.
@@ -102,6 +106,8 @@ BEFORE creating a mock response object:
   3. If the shape is unknown, capture a real response into `tests/fixtures/` instead of inventing one.
 ```
 
+**Concrete capture tools** for recording the real shape: `curl -s <url> | jq '.'` against a staging endpoint, Postman's "Save Response", Laravel's `Http::fake()` in record mode, or a Playwright network-trace export. Filter the captured payload with `jq` / `grep` to keep only the fields your fixture documents — **do not** dump unredacted secrets into `tests/fixtures/`.
+
 ### Anti-Pattern 5 — Tests as an afterthought
 
 Symptom: "Implementation complete, ready for testing." Implementation went in without tests. TDD was skipped, anti-patterns 1–4 are now likely.
@@ -120,6 +126,7 @@ Gate: a feature is not complete until a failing-then-passing test cycle ran for
 - A "complete" mock that mirrors a v1 API silently rots when v2 ships — link mock fixtures to a real recorded response and re-record on schema changes.
 - Layer 3 environment guards from [`defense-in-depth`](../defense-in-depth/SKILL.md) often expose anti-pattern 2: if a production guard fires only in tests, the test setup is wrong, not the guard.
 - Long mock setups (> 50% of the test) are a signal that integration tests would be simpler — consider it before piling on more mocks.
+- **Diagnose, do not brute-force.** If a test fails after a mock change, **never guess** at another mock tweak — drop a debugger / Xdebug breakpoint at the seam, observe the real call shape, then mock minimally. Two retries without a root-cause hypothesis = STOP and rethink.
 
 ## Do NOT
 

package/.agent-src/templates/AGENTS.md

@@ -1,25 +1,24 @@
 # {{project_name}}
 
 <!--
-  AGENTS.md entry point for AI coding agents. Installed by
-  `event4u/agent-config`. Fill placeholders (or run `/copilot-agents-init`)
-  and delete this comment. Keep thin; bulk prose belongs in the linked guide.
+  Fill placeholders or run `/agents init`, then delete this
+  comment. Iron Law — capability bullets, not path lists; paths rot.
+  Tool stubs (`CLAUDE.md`, `GEMINI.md`, `.cursorrules`) link here.
+  Anatomy + recipes: `.augment/contexts/contracts/agents-md-anatomy.md`.
 -->
 
-{{project_description}}
+> {{project_description}}
 
 ## Layers
 
-| Layer | Location | Purpose |
+| Layer | Location | Edits |
 |---|---|---|
-| **Shared package** | `.augment/`, `.agent-src/` | Installed skills / rules / commands — do not hand-edit |
-| **Project overrides** | `agents/overrides/` | Customizations of shared resources |
-| **Project docs** | `agents/` | Architecture, features, roadmaps, sessions, contexts |
-| **Agent settings** | `.agent-settings.yml` | Project-specific config consumed by skills |
+| Installed package | `.augment/`, `.agent-src/` | hands-off — managed by `event4u/agent-config` |
+| Project layer | `agents/`, `agents/overrides/`, `.agent-settings.yml` | your customizations and config |
 
 ## Pointers
 
-- **Filling out this AGENTS.md** — tech-stack / dev-setup / testing / quality / project-structure templates plus `/work` + `/implement-ticket` entry flow and multi-agent matrix: [`.augment/contexts/contracts/consumer-agents-md-guide.md`](.augment/contexts/contracts/consumer-agents-md-guide.md).
+- **Filling out this AGENTS.md** — section templates, capability bullets, multi-agent entry flow, monorepo per-package layout: [`.augment/contexts/contracts/consumer-agents-md-guide.md`](.augment/contexts/contracts/consumer-agents-md-guide.md).
 - **Behavior rules (always active)** — Iron Laws and routed rules that fire automatically while you work in this project: [`.augment/rules/`](.augment/rules/).
 - **Skills (on-demand expertise)** — domain skills surfaced by description; invoked when their trigger fires: [`.augment/skills/`](.augment/skills/).
 - **Commands (workflows)** — slash-commands the agent runs end-to-end (`/work`, `/implement-ticket`, `/commit`, `/create-pr`, …): [`.augment/commands/`](.augment/commands/).

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.29.0"
+    "version": "1.31.0"
   },
   "plugins": [
     {
@@ -22,9 +22,9 @@
         "./.claude/skills/agent-status",
         "./.claude/skills/agents",
         "./.claude/skills/agents-audit",
-        "./.claude/skills/agents-cleanup",
+        "./.claude/skills/agents-init",
         "./.claude/skills/agents-md-thin-root",
-        "./.claude/skills/agents-prepare",
+        "./.claude/skills/agents-optimize",
         "./.claude/skills/ai-council",
         "./.claude/skills/analysis-autonomous-mode",
         "./.claude/skills/analysis-skill-router",
@@ -64,10 +64,7 @@
         "./.claude/skills/context-document",
         "./.claude/skills/context-refactor",
         "./.claude/skills/conventional-commits-writing",
-        "./.claude/skills/copilot-agents",
-        "./.claude/skills/copilot-agents-init",
         "./.claude/skills/copilot-agents-optimization",
-        "./.claude/skills/copilot-agents-optimize",
         "./.claude/skills/copilot-config",
         "./.claude/skills/cost-report",
         "./.claude/skills/council",
@@ -169,7 +166,7 @@
         "./.claude/skills/onboard",
         "./.claude/skills/openapi",
         "./.claude/skills/optimize",
-        "./.claude/skills/optimize-agents",
+        "./.claude/skills/optimize-agents-dir",
         "./.claude/skills/optimize-augmentignore",
         "./.claude/skills/optimize-prompt",
         "./.claude/skills/optimize-rtk",
@@ -213,7 +210,7 @@
         "./.claude/skills/receiving-code-review",
         "./.claude/skills/refine-prompt",
         "./.claude/skills/refine-ticket",
-        "./.claude/skills/repomix",
+        "./.claude/skills/repomix-packer",
         "./.claude/skills/requesting-code-review",
         "./.claude/skills/research",
         "./.claude/skills/review-changes",

package/AGENTS.md

@@ -19,8 +19,7 @@ task ci                # full pipeline — green before PR
 - **Package self-orientation** — identity, four-wing cognition map, repo layout, tech stack, key-rules table, telemetry, command-suggester: [`docs/contracts/package-self-orientation.md`](docs/contracts/package-self-orientation.md).
 - **Kernel + Router** — 9 always-loaded Iron-Law rules, tier-1 / tier-2 routing, cost profiles, per-rule char caps enforced by `task lint-rule-budget`: [`kernel-membership`](docs/contracts/kernel-membership.md) + [`rule-router`](docs/contracts/rule-router.md).
 - **Multi-tool projection** — Augment, Claude Code, Cursor, Cline, Windsurf, Gemini CLI, Claude.ai bundle pipeline that ships from `.agent-src/` to consumer surfaces: [`docs/architecture.md`](docs/architecture.md#cloud-bundle-pipeline).
-- **Iron-Law rules when editing this repo** — portability, source-of-truth, skill-quality: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md).
-- **Thin-Root contract** governing **this** file (cap, pointer ratio, emergency-triage block) — read before editing AGENTS.md: [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
+- **Editing this repo** — Iron-Law rules (portability, source-of-truth, skill-quality) and the Thin-Root contract (caps · pointer-ratio · triage block) governing AGENTS.md: [`augment-portability`](.agent-src/rules/augment-portability.md), [`augment-source-of-truth`](.agent-src/rules/augment-source-of-truth.md), [`skill-quality`](.agent-src/rules/skill-quality.md), [`agents-md-thin-root`](.agent-src/skills/agents-md-thin-root/SKILL.md).
 - **Consumer story + architecture deep-dive** — what the package does for installers and how it ships: [`README.md`](README.md), [`docs/architecture.md`](docs/architecture.md).
 
 ## Emergency triage — read this when nothing else is reachable

package/CHANGELOG.md

@@ -318,6 +318,92 @@ 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

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. |
@@ -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`: