@event4u/agent-config 1.28.0 → 1.31.0

package/.agent-src/commands/agents.md

@@ -1,26 +1,31 @@
 ---
 name: agents
-description: Agents-folder orchestrator — routes to audit, cleanup, prepare
+description: Agent-layer orchestrator — routes to init, optimize, audit. Covers AGENTS.md and its multi-tool stubs (CLAUDE.md, GEMINI.md, copilot-instructions.md, .cursorrules).
 cluster: agents
 disable-model-invocation: true
 suggestion:
   eligible: true
-  trigger_description: "audit agents folder, prepare agents structure, clean up agent docs"
-  trigger_context: "user wants to inspect, scaffold, or curate the agents/ tree"
+  trigger_description: "initialize agent layer, optimize AGENTS.md, audit agent infrastructure, AGENTS.md health-check"
+  trigger_context: "user wants to bootstrap, refactor, or health-check the agent layer (AGENTS.md + tool stubs + rules + skills)"
 ---
 
 # /agents
 
-Top-level orchestrator for the `/agents` family. Replaces 3 standalone
-commands with a single entry point + sub-command dispatch.
+Top-level orchestrator for the `/agents` family — the **file-family
+cluster**: `AGENTS.md`, its multi-tool stubs (`CLAUDE.md`, `GEMINI.md`,
+`.github/copilot-instructions.md`, `.cursorrules`), and the surrounding
+agent infrastructure (rules, skills, pointers).
+
+> Looking for `agents/` folder operations (scaffold, folder-audit,
+> folder-cleanup)? Those live under [`/optimize agents-dir`](optimize/agents-dir.md).
 
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
 |---|---|---|
-| `/agents audit` | `commands/agents/audit.md` | Audit `agents/` for outdated docs, duplicates, orphaned overrides |
-| `/agents cleanup` | `commands/agents/cleanup.md` | Execute cleanup actions from a prior audit |
-| `/agents prepare` | `commands/agents/prepare.md` | Scaffold the `agents/` directory structure |
+| `/agents init` | `commands/agents/init.md` | Bootstrap the agent layer — create `AGENTS.md` + tool stubs from the canonical template |
+| `/agents optimize` | `commands/agents/optimize.md` | Refactor `AGENTS.md` to the Thin-Root contract; propagate to multi-tool stubs |
+| `/agents audit` | `commands/agents/audit.md` | Read-only health check — token overhead, rule triggers, AGENTS.md health, stale references |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -29,13 +34,13 @@ Sub-command names match the locked contract in
 
 1. Parse the user's argument: `/agents <sub-command> [args]`.
 2. Look up the sub-command in the table above.
-3. Load the body of the routed file and follow its `## Instructions` section
+3. Load the body of the routed file and follow its `## Steps` section
    verbatim with the remaining args.
 4. If the sub-command is unknown or missing, print the table above and ask:
 
-   > 1. audit — find outdated docs, duplicates, orphaned overrides
-   > 2. cleanup — execute actions from a prior audit
-   > 3. prepare — scaffold the agents/ tree
+   > 1. init — bootstrap AGENTS.md + tool stubs
+   > 2. optimize — refactor AGENTS.md to the Thin-Root contract
+   > 3. audit — read-only health check on the agent layer
 
 ## Rules
 
@@ -44,3 +49,5 @@ Sub-command names match the locked contract in
 - **Do NOT chain sub-commands.** One `/agents <sub>` per turn.
 - If the user invokes `/agents` with no argument, **show the menu** — do
   not guess which sub-command they meant.
+- **Edit `.agent-src.uncompressed/` only.** `.agent-src/` and `.augment/`
+  regenerate from source.

package/.agent-src/commands/optimize/agents-dir.md

@@ -0,0 +1,111 @@
+---
+name: optimize:agents-dir
+cluster: optimize
+sub: agents-dir
+description: Manage the agents/ directory — scaffold, folder-audit, fix. Single command with three modes (--scaffold / --audit / --fix); default = interactive wizard.
+skills: [agents-audit, agent-docs-writing, override-management, module-management]
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "scaffold agents folder, audit agents directory, fix agents docs, clean up overrides, prepare module agents"
+  trigger_context: "user wants to inspect, scaffold, or curate the agents/ tree (NOT AGENTS.md — that's /agents)"
+---
+
+# /optimize agents-dir
+
+One command for everything that touches the **`agents/` folder** — the
+project's prose layer (features, contexts, roadmaps, overrides) and the
+mirror dirs under `app/Modules/*/agents/`. Replaces the legacy three-leaf
+surface (`/agents prepare` + `/agents audit` + `/agents cleanup`) with
+one entry-point and three explicit modes.
+
+> **Not for `AGENTS.md`** — the root-level Markdown file and its tool
+> stubs (`CLAUDE.md`, `GEMINI.md`, `copilot-instructions.md`) live under
+> [`/agents`](../agents.md) (`init / optimize / audit`).
+
+## Modes
+
+| Flag | Mode | Was | What it does |
+|---|---|---|---|
+| `--scaffold` | scaffold | `/agents prepare` | Create `agents/`, `agents/features/`, `agents/contexts/`, `agents/roadmaps/`, module mirrors, `.gitkeep` files |
+| `--audit` | folder-audit | `/agents audit` | Read-only inventory of `agents/`, module agents, overrides; flag duplicates, orphans, structural drift |
+| `--fix` | fix | `/agents cleanup` | Execute actions from a prior `--audit` (or roadmap) — move, merge, delete, update; per-action confirmation |
+
+**No flag → interactive wizard.** Print the table above, ask:
+
+```
+> 1. scaffold — set up the agents/ tree (first-time setup)
+> 2. audit — inventory and find issues
+> 3. fix — execute actions from a prior audit
+```
+
+## Mode dispatch
+
+After a mode is selected, follow the matching procedure verbatim. Each
+mode preserves the behavior of the old leaf command exactly — only the
+surface changes.
+
+### `--scaffold` (was `/agents prepare`)
+
+1. **Verify project root** — look for `composer.json`, `artisan`, or `package.json`.
+2. **Create directory structure** — `agents/{roadmaps,features,contexts}/.gitkeep` + `.augment/guidelines/php/.gitkeep`. Skip dirs that already exist with content.
+3. **Module support** — if `app/Modules/` exists, mirror the layout in every module: `app/Modules/{Module}/agents/{roadmaps,features,contexts}/.gitkeep`.
+4. **Verify templates** — confirm `.augment/templates/{features,roadmaps,contexts}.md` exist; warn on missing.
+5. **Clean up old templates** — offer to delete legacy `agents/features/template.md` etc. (now in `.augment/templates/`); ask before delete.
+6. **Show summary** — table with status per directory and template; flag missing as `⚠️`.
+
+**Rules:** never overwrite existing files; only add `.gitkeep` to truly empty dirs; ask before deleting old templates.
+
+### `--audit` (was the folder side of `/agents audit`)
+
+1. **Inventory all agent docs** — `find agents/ -maxdepth 1`, `agents/features/`, `agents/contexts/`, `agents/overrides/`, `.augment/guidelines/`, `app/Modules/*/agents/`. For each: filename, first heading, size, last `git log` date.
+2. **Module coverage** — for every `app/Modules/*/`: docs count, presence of description file, features dir, contexts dir; flag inactive modules with no docs as `🔵 Info` only.
+3. **Scan overrides** — for every `agents/overrides/*.md`: extract `Mode:` (`extend`/`replace`) and `Original:` headers; check the original file exists; flag orphans.
+4. **Classify documents** — `Architecture / Convention / Pattern / Feature / Context / Module Doc / Override / Unclear`.
+5. **Detect issues**:
+   - Structural — files in wrong dirs, naming inconsistencies, kebab-case violations.
+   - Content — verify class/method/path references against the actual codebase via `codebase-retrieval` or file checks; flag stale references.
+   - Duplication — `agents/` ↔ `.augment/skills/`, root ↔ `.augment/guidelines/`, root ↔ module docs.
+   - Coverage gaps — active modules without docs, complex areas without contexts.
+6. **Display audit report** — sectioned table (Inventory · Module Agents · Overrides · Issues · Duplicates · Gaps) with severity buckets `🔴 Critical`, `🟡 Warning`, `🔵 Info`, `⚪ Clean`.
+7. **Offer improvement roadmap**:
+   ```
+   > 1. Yes — create agents/roadmaps/agents-cleanup.md
+   > 2. Show recommendations only (no file)
+   > 3. No — audit was enough
+   ```
+   Roadmap phases: critical fixes → structural cleanup → fill gaps → cleanup.
+8. **Offer next steps** — `/optimize agents-dir --fix`, `/context refactor`, or done.
+
+**Rules:** read-only — no file edits; do NOT audit `agents/roadmaps/` or `app/Modules/*/agents/roadmaps/` (separate lifecycle); do NOT audit `.augment/` (route to `/agents audit`); be specific (file, reference, what's wrong); don't flag inactive modules.
+
+### `--fix` (was `/agents cleanup`)
+
+1. **Locate the audit roadmap** — most recent `agents/roadmaps/road-to-agents-cleanup*.md` (or named cleanup roadmap from a prior `--audit` run). Missing → recommend `/optimize agents-dir --audit` first; allow `--ad-hoc` only on explicit override.
+2. **Show action plan** — phases from the roadmap (Critical fixes · Structural cleanup · Fill gaps · Cleanup) with action counts; ask which phase to start.
+3. **Execute actions** — for each: per-action confirmation, then run the matching workflow:
+   - **Move** — move file + update references in `.augment/` skills/commands and other docs.
+   - **Merge** — preview merged content, confirm, write merged file, delete originals, update references.
+   - **Delete** — preview file, confirm, delete, scrub references.
+   - **Update** — apply explicit content changes (remove stale refs, refresh sections, add missing info).
+   - **Create context** — hand off to `/context create` with area pre-selected.
+4. **Update roadmap progress** — flip `[ ]` → `[x]` after each action; show progress bar. Per `verbosity.routine_confirmations`: `false` → continue silently, user can interrupt; `true` → confirm next.
+5. **Summary** — gated by `verbosity.post_action_reports` (`off` / `minimal` / `full`); minimal = one line counts (moved · merged · deleted · updated · remaining).
+
+**Rules:** confirm before every destructive action; always update references when moving/renaming; update the roadmap after each completed action; show file content before delete; check `.augment/` references too.
+
+## What this command does NOT do
+
+- **No edits to `AGENTS.md`** or its tool stubs — that's [`/agents optimize`](../agents/optimize.md).
+- **No edits to rules / skills / `.augment/`** — that's [`/agents audit`](../agents/audit.md), `/optimize skills`, or `skill-reviewer`.
+- **No commits, no push, no PR** — finishing is a user decision per
+  [`commit-policy`](../../rules/commit-policy.md).
+- **No edits to `.agent-src/` or `.augment/`** — those regenerate from
+  `.agent-src.uncompressed/`. Edit the source.
+
+## See also
+
+- [`/agents`](../agents.md) — `init / optimize / audit` for `AGENTS.md` and tool stubs.
+- [`agent-docs-writing`](../../skills/agent-docs-writing/SKILL.md) — voice, structure, anchor conventions for prose under `agents/`.
+- [`agents-audit`](../../skills/agents-audit/SKILL.md) — folder-audit heuristics and severity matrix.
+- [`override-management`](../../skills/override-management/SKILL.md) — `extend` vs `replace` semantics and orphan detection.

package/.agent-src/commands/optimize.md

@@ -1,25 +1,27 @@
 ---
 name: optimize
-description: Optimize orchestrator — routes to skills, agents, augmentignore, rtk-filters
+description: Optimize orchestrator — routes to skills, agents-dir, augmentignore, rtk-filters
 cluster: optimize
 disable-model-invocation: true
 suggestion:
   eligible: true
-  trigger_description: "optimize my skills, audit agents, tune augmentignore, optimize rtk filters"
-  trigger_context: "maintainer auditing or trimming agent infrastructure"
+  trigger_description: "optimize my skills, manage agents directory, tune augmentignore, optimize rtk filters"
+  trigger_context: "maintainer auditing or trimming the agent layer (NOT AGENTS.md — that's /agents)"
 ---
 
 # /optimize
 
-Top-level orchestrator for the `/optimize` family. Replaces 4 standalone
-commands with a single entry point + sub-command dispatch.
+Top-level orchestrator for the `/optimize` family.
+
+> Looking for `AGENTS.md` operations (init, refactor, audit)? Those
+> live under [`/agents`](agents.md) (`init / optimize / audit`).
 
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
 |---|---|---|
 | `/optimize skills` | `commands/optimize/skills.md` | Audit skills — measure baseline, find duplicates, run linter |
-| `/optimize agents` | `commands/optimize/agents.md` | Audit agent infrastructure — token overhead, rule triggers, AGENTS.md |
+| `/optimize agents-dir` | `commands/optimize/agents-dir.md` | Manage the `agents/` directory — `--scaffold` / `--audit` / `--fix` (interactive wizard if no flag) |
 | `/optimize augmentignore` | `commands/optimize/augmentignore.md` | Create or refine `.augmentignore` based on actual stack |
 | `/optimize rtk` | `commands/optimize/rtk.md` | Create or refine project-local rtk filters |
 
@@ -30,12 +32,12 @@ Sub-command names match the locked contract in
 
 1. Parse the user's argument: `/optimize <sub-command> [args]`.
 2. Look up the sub-command in the table above.
-3. Load the body of the corresponding `commands/optimize-<sub>.md` file and
+3. Load the body of the corresponding `commands/optimize/<sub>.md` file and
    follow its `## Steps` (or `## Instructions`) section verbatim.
 4. If the sub-command is unknown or missing, print the menu and ask:
 
    > 1. skills — audit skills (find duplicates, run linter)
-   > 2. agents — audit agent infrastructure (token overhead, rule triggers)
+   > 2. agents-dir — scaffold / audit / fix the `agents/` tree
    > 3. augmentignore — create or refine `.augmentignore`
    > 4. rtk — create or refine project-local rtk filters
 

package/.agent-src/contexts/communication/rules-auto/guidelines-mechanics.md

@@ -5,6 +5,12 @@ Full table of available coding guidelines for the
 holds the obligation surface (always check the relevant guideline
 before writing or reviewing code); this file is the catalog.
 
+## Universal (`docs/guidelines/`)
+
+| File | Topic |
+|---|---|
+| `code-clarity.md` | Cross-language clarity rules — inline single-use values, carve-outs (side effects, loops, type narrowing, debugger) |
+
 ## PHP (`docs/guidelines/php/`)
 
 | File | Topic |

package/.agent-src/contexts/communication/rules-auto/slash-command-routing-policy-mechanics.md

@@ -4,7 +4,7 @@ Lookup table for the `slash-command-routing-policy` rule. Lists the
 locked clusters and their sub-commands so the rule itself can stay at
 its current LOC while still reflecting the full surface. Source of
 truth for the cluster names is
-[`docs/contracts/command-clusters.md`](../../../../../docs/contracts/command-clusters.md);
+[`docs/contracts/command-clusters.md`](../../../../../../docs/contracts/command-clusters.md);
 this file mirrors that contract for runtime lookup. Linter:
 `scripts/check_cluster_patterns.py` (verifies dispatcher shape).
 
@@ -16,14 +16,13 @@ this file mirrors that contract for runtime lookup. Linter:
 | `/optimize` | 1 | `agents` · `augmentignore` · `rtk` · `skills` | `/optimize-agents` · `/optimize-augmentignore` · `/optimize-rtk-filters` · `/optimize-skills`                                                   |
 | `/feature` | 1 | `explore` · `plan` · `refactor` · `roadmap` | `/feature-explore` · `/feature-plan` · `/feature-refactor` · `/feature-roadmap`                                                                 |
 | `/chat-history` | 2 | `show` | `/chat-history` (legacy status) — `resume` / `clear` / `checkpoint` removed in `road-to-chat-history-hook-only`                                 |
-| `/agents` | 2 | `audit` · `cleanup` · `prepare` | `/agents-audit` · `/agents-cleanup` · `/agents-prepare`                                                                                         |
+| `/agents` | 2 | `init` · `optimize` · `audit` | `/copilot-agents-init` · merger of `/optimize-agents-md` + `/copilot-agents-optimize` · `/optimize-agents` (folder ops moved to `/optimize:agents-dir`) |
 | `/memory` | 2 | `add` · `load` · `promote` · `propose` | `/memory-add` · `/memory-full` · `/memory-promote` · `/propose-memory`                                                                          |
 | `/roadmap` | 2 | `create` · `process-step` · `process-phase` · `process-full` | `/roadmap-create` · `/roadmap-process` (replaced — autonomous, no per-step gate; `process-phase` is the default execution scope)                |
 | `/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 | flag: `--in-chunks` | `/commit:in-chunks`                                                                                                                             |
 | `/create-pr` | 2 | flag: `--description-only` | `/create-pr:description-only`                                                                                                                   |

package/.agent-src/contexts/contracts/agents-md-anatomy.md

@@ -0,0 +1,132 @@
+# AGENTS.md Anatomy — outboard reference
+
+> Companion context to the
+> [`agents-md-thin-root`](../../skills/agents-md-thin-root/SKILL.md)
+> skill. Holds the long-form anatomy guidance that does not fit
+> inside the skill body without breaching its size budget.
+
+## Iron Law — Capabilities over Structure
+
+Every entry in AGENTS.md describes **what the project can do** or
+**where to learn more**, never **where individual files live**.
+
+```
+A FILE PATH WITHOUT A WHY-CLAUSE IS DEAD WEIGHT.
+PATH ENUMERATION (≥ 3 PATHS WITHOUT POINTERS) IS A LINT WARNING.
+```
+
+Path lists rot every refactor; capability lists survive structural
+churn because they describe intent. Concrete substitutions:
+
+| Anti-pattern (path enumeration) | Capability rewrite |
+|---|---|
+| `- src/auth/`<br>`- src/auth/jwt.ts`<br>`- src/auth/middleware.ts` | `- **Authentication** — OAuth + JWT session handling: [`src/auth/`](src/auth/)` |
+| `- packages/payments/`<br>`- packages/billing/` | `- **Billing** — Stripe Checkout + invoice generation, dunning + tax: [`docs/billing.md`](docs/billing.md)` |
+| Three bullets listing test directories | One pointer to the testing strategy doc with a *why*-clause |
+
+A pointer is **substantive** only if its surrounding sentence carries
+a *why*-clause ≥ 60 chars. Bare paths get filtered out by the lint.
+
+## 1-liner project description slot
+
+The first prose line under the project title is the **only place** the
+agent learns what the repo is in one sentence when retrieval is
+degraded. Required content:
+
+```
+> {What it is} — {primary capability} for {audience}, {differentiator}.
+```
+
+✅ Right: `> Multi-tenant SaaS billing — Stripe-backed subscription
+and invoicing for B2B sellers, audit-grade ledger.`
+❌ Wrong: `> A modern web app built with Next.js and TypeScript.`
+(stack ≠ capability; an agent already knows what those are.)
+
+## Multi-tool symlink strategy
+
+`AGENTS.md` is the canonical entry point. Tool-specific files
+(`CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`) point at
+the same content via a symlink-or-stub pattern. Two acceptable shapes:
+
+**Symlink** (POSIX, monorepo-friendly):
+
+```bash
+ln -s AGENTS.md CLAUDE.md
+ln -s AGENTS.md GEMINI.md
+ln -s AGENTS.md .cursorrules
+```
+
+**Stub** (Windows-safe, generation-pipeline-friendly):
+
+```markdown
+<!-- CLAUDE.md -->
+> See [`AGENTS.md`](AGENTS.md) — single source of truth for agent
+> instructions in this repo.
+```
+
+Do not duplicate AGENTS.md content into the tool-specific files; the
+agent ends up with two diverging versions and the budget is paid
+twice. The package's `task generate-tools` pipeline produces stubs
+deterministically — never hand-edit them.
+
+## Monorepo — per-package AGENTS.md
+
+Each top-level package (or app, depending on layout) gets its own
+`AGENTS.md` at the package root, **not** a section inside the
+monorepo-root file. Why:
+
+1. Agents working in `packages/foo/` retrieve the nearest `AGENTS.md`
+   first — irrelevant siblings stay out of the budget.
+2. The monorepo-root `AGENTS.md` becomes a navigation surface that
+   points at each package's entry, capability-style:
+   `- **Web app** — Next.js storefront and customer dashboard:
+   [`apps/web/AGENTS.md`](apps/web/AGENTS.md)`.
+3. Per-package emergency-triage blocks answer the five canonical
+   questions in the package's local idiom (own lint / test entry,
+   own source-of-truth path).
+
+Anti-pattern: a single 6 KB monorepo `AGENTS.md` with five
+package-specific sections. Spend lives in the wrong budget and every
+package edit touches the same hot file.
+
+## Refactor recipe — bloated AGENTS.md → Thin-Root
+
+1. **Snapshot.** `wc -c AGENTS.md` and stash a copy of the
+   pre-refactor file (e.g. `AGENTS.md.before` in your scratch dir)
+   so you can diff before / after.
+2. **Section inventory.** List every `## ` heading + its char-count.
+   Mark `keep-inline` (Iron-Law-adjacent, ≤ 200 chars) vs.
+   `outboard-candidate`.
+3. **Path-enumeration sweep.** Find every line that is just a path
+   inside backticks with no *why*-clause; collapse runs of three or
+   more into a single capability pointer.
+4. **Outboard.** Move each `outboard-candidate` into
+   `agents/contexts/`, `docs/contracts/`, an existing rule body, or
+   an existing skill body. Replace in-file with a substantive
+   pointer. Never invent a new top-level dir.
+5. **Verify.** Run `python3 scripts/lint_agents_md.py` until green;
+   `wc -c AGENTS.md` ≤ target cap; emergency-triage block intact.
+
+## Common gotchas
+
+- **"Quick reference" sections.** A two-line table of common commands
+  feels useful but doubles every package release. Outboard to the
+  README's quickstart and link with one pointer.
+- **Tech-stack dumps.** "We use React, Tailwind, tRPC, Postgres, …"
+  costs budget without unblocking decisions. Move to a single
+  `## Stack` pointer at `docs/architecture.md#stack`.
+- **Roadmap snippets.** Roadmaps move every sprint; pin the agent to
+  the directory (`agents/roadmaps/`) and let it discover the active
+  one rather than naming the current file.
+- **Per-feature subsections.** "How auth works", "How billing works"
+  belong in capability docs, not in the root entry. AGENTS.md
+  references them with one *why*-clause line each.
+
+## See also
+
+- [`agents-md-thin-root`](../../skills/agents-md-thin-root/SKILL.md)
+  — caps, pointer-ratio, pointer-anatomy, emergency-triage contract.
+- [`emergency-triage-block`](emergency-triage-block.md) — canonical
+  source for the five-question block both AGENTS.md variants embed.
+- [`consumer-agents-md-guide`](consumer-agents-md-guide.md) — section
+  templates a consumer fills in after install.

package/.agent-src/skills/agents-md-thin-root/SKILL.md

@@ -31,6 +31,10 @@ Use when:
 
 Augment Code injects `AGENTS.md` verbatim into every workspace prompt. Each kilobyte spent here permanently consumes the 49,512-char workspace-guidelines budget shared with always-rules and auto-rule registry stubs. The Thin-Root pattern keeps the entry point a navigation surface (pointers + intent) and pushes deep detail into files Augment loads on demand via `load_context` or that other tools fetch only when their search retrieves them. Strategic council R2 (2026-05-08, Sonnet 4.5 / Opus 4.1 / gpt-4o / o1) converged on the contract codified below as the minimum guard against AGENTS.md re-bloat.
 
+## Iron Law — Capabilities over Structure
+
+Every entry describes **what** the project does or **where** to learn more — never **where** individual files live. Path lists rot every refactor and poison context; capability pointers survive structural churn. Full anatomy with rewrite recipes, monorepo guidance, and multi-tool symlink strategy: [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md).
+
 ## The contract — hard caps
 
 | File | FAIL above | WARN above | Target |
@@ -106,6 +110,8 @@ Same procedure, applied to `.agent-src.uncompressed/templates/AGENTS.md`. Hard c
 - **Emergency-triage drift.** Editing the in-file emergency-triage block instead of the canonical `.agent-src.uncompressed/contexts/contracts/emergency-triage-block.md` causes the package-root and consumer-template versions to diverge silently. Always edit the canonical file and let the lint diff pull both back in sync.
 - **Cap inversion under WARN.** A 2,250-char AGENTS.md (above 2,200 WARN, below 2,500 FAIL) is a yellow signal not a green one — every additional sentence raises the probability of the next FAIL. Treat WARN as the spend boundary, not a buffer.
 - **Char-count includes frontmatter.** `wc -c` counts every byte including the YAML preamble, blank lines, and the trailing newline. Stripping a section to "look smaller" without re-running `wc -c` understates the true budget impact.
+- **Path enumeration.** A run of three or more bare `` `path/to/dir/` `` bullets without *why*-clauses is the classic re-bloat pattern. The lint emits a WARN at ≥ 3 such lines. Collapse them into one capability-style pointer — see the recipe in [`agents-md-anatomy § Iron Law`](../../contexts/contracts/agents-md-anatomy.md#iron-law--capabilities-over-structure).
+- **Tool-specific duplicates.** Copy-pasting AGENTS.md into `CLAUDE.md` / `GEMINI.md` / `.cursorrules` doubles the budget cost across tools. Use the symlink-or-stub pattern in [`agents-md-anatomy § Multi-tool symlink strategy`](../../contexts/contracts/agents-md-anatomy.md#multi-tool-symlink-strategy) instead.
 
 ## Output format
 
@@ -119,7 +125,8 @@ When invoked as a planning step, produce:
 
 ## See also
 
-- [`copilot-agents-optimization`](../copilot-agents-optimization/SKILL.md) — sibling skill for `.github/copilot-instructions.md`; runs alongside Thin-Root in `/optimize/agents`.
+- [`agents-md-anatomy`](../../contexts/contracts/agents-md-anatomy.md) — Capabilities-over-Structure Iron Law, multi-tool symlink strategy, monorepo per-package layout, refactor recipe, full gotcha catalog.
+- [`copilot-agents-optimization`](../copilot-agents-optimization/SKILL.md) — sibling skill for `.github/copilot-instructions.md`; runs alongside Thin-Root in `/agents optimize`.
 - [`agent-docs-writing`](../agent-docs-writing/SKILL.md) — broader documentation-structure context for navigating outboard targets.
 - [`size-enforcement`](../../rules/size-enforcement.md) — covers per-skill / per-rule / per-command size budgets; AGENTS.md caps live in this skill instead.
 - [`ADR-004-rule-governance-pruning`](../../../docs/decisions/ADR-004-rule-governance-pruning.md) — captures the rule-governance pruning that freed the workspace-guidelines budget; the Thin-Root caps build on that headroom.

package/.agent-src/skills/async-python-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: async-python-patterns
+description: "Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized."
+source: package
+status: active
+refresh_trigger: "Python ships a new structured-concurrency primitive (post-TaskGroup), OR ≥30% of cited upstream cookbook examples become deprecated, OR the cited libraries (aiohttp, httpx, anyio, trio) cut a major version with breaking async surface changes."
+sunset_criterion: "When `https://docs.python.org/3/library/asyncio.html` ships an in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+---
+
+# async-python-patterns
+
+Decision framework for picking the right Python asyncio primitive. **The pattern cookbook lives upstream** (links in § Provenance) — this skill is the predicate, not the recipe library. Sunset-policy compliant: the 600+ lines of language-specific cookbook stay in authoritative Python docs.
+
+## When to use
+
+- Designing a new async I/O-bound service (FastAPI, aiohttp, async DB client).
+- Reviewing a diff that introduces `asyncio.gather`, `asyncio.create_task`, `TaskGroup`, `as_completed`, or `wait_for`.
+- Mixing sync and async code (calling sync libs from async context, or vice versa).
+- Diagnosing event-loop blocking, never-awaited warnings, or cancellation leaks.
+
+Do NOT use when:
+
+- The work is CPU-bound — async will not help; route to multiprocessing or threadpool.
+- The runtime is not Python — read the host runtime's concurrency guide.
+- The fix is a single missing `await` — read the upstream tutorial directly.
+
+## Decision framework
+
+### Step 1 — Verify async is the right tool
+
+```
+Workload is:
+  I/O-bound, many concurrent waits  → async fits (network, disk, IPC).
+  CPU-bound (parsing, math, crypto) → async is wrong; use ProcessPoolExecutor.
+  Mixed                              → async shell + run_in_executor for CPU bursts.
+  Single sequential call             → don't introduce async; sync is simpler.
+```
+
+### Step 2 — Pick the concurrency primitive
+
+```
+Run N independent coroutines, ALL must complete:
+  Same trust level, exceptions cancel siblings  → asyncio.TaskGroup (3.11+; preferred).
+  Pre-3.11 OR exceptions must NOT cancel peers  → asyncio.gather(*, return_exceptions=...).
+
+Run N coroutines, react to results as they finish:
+  → asyncio.as_completed (yields completed futures in finish order).
+
+Run N coroutines, race to first success / failure:
+  → asyncio.wait(..., return_when=FIRST_COMPLETED) + cancel pending.
+
+Schedule fire-and-forget background work:
+  → asyncio.create_task + keep a strong reference (else GC eats it).
+  Forgetting the reference is the #1 silent-failure source.
+
+Bound the wait time:
+  → asyncio.wait_for(coro, timeout=...)  → raises TimeoutError on expiry.
+  → asyncio.timeout(...) context manager (3.11+; preferred when many awaits share a deadline).
+
+Bound concurrency (rate-limit, connection pool):
+  → asyncio.Semaphore(n); acquire around the awaitable.
+```
+
+### Step 3 — Bridge sync ↔ async correctly
+
+```
+Async code calls sync, blocking, function:
+  Short pure-CPU              → fine, accept the block (microseconds).
+  Long, blocking, or I/O-sync → await loop.run_in_executor(None, fn, *args).
+  Library has async sibling   → switch the library (httpx vs requests, aiosqlite vs sqlite3).
+
+Sync code calls async function:
+  Top-level entrypoint        → asyncio.run(coro()).
+  Inside running loop         → never asyncio.run; create_task + await it.
+  Test suite                  → pytest-asyncio fixture; never raw run() in tests.
+```
+
+### Step 4 — Cancellation discipline
+
+Every long-running coroutine MUST be cancellation-safe:
+
+- Catch `asyncio.CancelledError`, perform cleanup, **re-raise**. Swallowing it silently breaks the propagation chain.
+- Use `try / finally` (or `async with`) around resource acquisition so cancellation cannot leak file handles, DB connections, locks.
+- Detached `create_task` without a strong reference is undefined behavior; either store the task or use a TaskGroup.
+
+### Step 5 — Don't block the event loop
+
+A single blocking call (sync I/O, time.sleep, CPU-heavy parse, large JSON load) freezes every coroutine. Audit every leaf function under `async def`:
+
+- Sleep → `await asyncio.sleep`, never `time.sleep`.
+- HTTP → `httpx.AsyncClient` / `aiohttp`, never `requests`.
+- DB → `asyncpg` / `aiosqlite` / `motor`, never the sync driver.
+- File → `aiofiles` for hot-paths, or `run_in_executor` for one-shots.
+
+## Procedure: Apply to a new async feature
+
+1. Run Step 1; reject if work is CPU-bound.
+2. Sketch the call graph; tag each `await` site with its primitive (Step 2).
+3. Mark every sync↔async boundary; pick the bridge per Step 3.
+4. For each long-running coroutine, write the cancel-safety contract (Step 4).
+5. Grep the leaf calls for blocking sins (Step 5); replace or push to executor.
+6. Hand the sketch to a reviewer **before** coding; cite this skill.
+
+## Output format
+
+1. Call-graph table: coroutine · concurrency primitive · timeout · cancel-safety note.
+2. Sync↔async boundary list: site · bridge · justification.
+3. Blocking-call audit: leaf function · status (async / executor / accepted-block + reason).
+4. Cancel-safety contract for each background task.
+
+## Gotcha
+
+- "It works in my REPL" — `asyncio.run` inside an already-running loop (Jupyter, FastAPI startup) raises `RuntimeError`. Use `await` directly or `nest_asyncio` (last resort).
+- `asyncio.gather` swallows the second exception silently; use `return_exceptions=True` and inspect, or use `TaskGroup` (cancels all on first error, surfaces the group).
+- `create_task` results that nobody awaits look fine until the program exits and Python prints `Task was destroyed but it is pending!`. Always `await` or use a TaskGroup.
+- `wait_for` on a non-cancellation-safe coroutine leaks resources; the timeout cancels the task but cleanup never runs.
+- Libraries that "support async" via thread pools (e.g. `requests-async`) often re-block the loop under load; verify with the cited upstream library docs, not the README.
+
+## Do NOT
+
+- Do NOT call `asyncio.run` from a running loop.
+- Do NOT swallow `CancelledError` without re-raising.
+- Do NOT call sync blocking I/O from async paths without `run_in_executor`.
+- Do NOT spawn `create_task` without storing the reference (or using TaskGroup).
+- Do NOT inline the asyncio cookbook into this skill — externalize per Sunset Policy.
+
+## Auto-trigger keywords
+
+- asyncio
+- async / await
+- gather / TaskGroup / wait_for
+- event loop blocking
+- cancellation
+- sync to async bridge
+
+## Provenance
+
+- Adopted from: `Microck/ordinary-claude-skills@8f5c83174f7aa683b4ddc7433150471983b93131:skills_all/async-python-patterns/SKILL.md` (MIT, © 2025 Microck) — **Sunset Policy applied**: 694-line cookbook source reduced to a ~140-line decision framework; pattern catalogues externalized to upstream docs below.
+- Externalized cookbook:
+  - asyncio core: https://docs.python.org/3/library/asyncio.html · https://docs.python.org/3/library/asyncio-task.html
+  - TaskGroup (3.11+): https://docs.python.org/3/library/asyncio-task.html#task-groups
+  - Structured concurrency: https://anyio.readthedocs.io · https://trio.readthedocs.io
+  - Async HTTP: https://www.python-httpx.org/async/ · https://docs.aiohttp.org/en/stable/
+  - Async DB: https://magicstack.github.io/asyncpg/ · https://aiosqlite.omnilib.dev/
+- Cross-linked: [`error-handling-patterns`](../error-handling-patterns/SKILL.md), [`mcp-builder`](../mcp-builder/SKILL.md), [`api-design`](../api-design/SKILL.md), [`performance`](../performance/SKILL.md).
+- Provenance registry: `agents/contexts/skills-provenance.yml` (entry: `async-python-patterns`).
+- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.

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

@@ -32,6 +32,35 @@ A command is **user-invoked** and carries `disable-model-invocation: true`.
 A skill is model-invoked via description routing. If both audiences apply,
 author as a skill and add a thin command that delegates to it.
 
+## Commands ARE Claude skills (projection reality)
+
+Every `.agent-src.uncompressed/commands/{name}.md` projects to
+`.claude/skills/{slug}/SKILL.md` via `scripts/compress.py`
+(`generate_claude_commands`). Nested commands flatten with `-`
+(`council/default.md` → `council-default`). Skills + commands share the
+**same `.claude/skills/` namespace** — Claude does not distinguish them.
+
+Authoring consequences:
+
+* Frontmatter `description` is Claude's **routing surface**. Generic
+  phrasing → undertriggering even with `disable-model-invocation: true`,
+  because the in-host suggester, fuzzy search, and any tooling that
+  scans `.claude/skills/` ranks by description match.
+* `disable-model-invocation: true` blocks **automatic** invocation only.
+  It does NOT remove the command from discovery surfaces. Weak
+  description = invisible to the suggester even when intent matches.
+* Trigger phrasing follows the same Iron Law as skill descriptions:
+  name 2+ trigger classes (domains, symptoms, user phrasing), end with
+  the `... even when the user just says ...` tail, ≤ 200 chars. See
+  `skill-writing` § 1b for the canonical before/after.
+* `suggestion.trigger_description` / `suggestion.trigger_context` are
+  **separate** from frontmatter `description` — they drive the in-host
+  suggester (`command-suggestion-policy`), not Claude's skill router.
+  Both matter, both must be precise.
+
+Bottom line: write the command's `description` as if a skill router
+will read it — because one will.
+
 ## Procedure
 
 ### 0. Run the Drafting Protocol
@@ -149,6 +178,26 @@ multi-paragraph explanation, extract it into a skill and call it.
 * 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 commands 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 file under review** and to
+**future** edits. The baseline table is informational so reviewers can
+spot intent (fix-now vs. backlog) without diffing the full lint output.
+See `agents/analysis/lint-warning-triage.md` for the 3-bucket reference.
+
 ## Output format
 
 1. Complete command file at `.agent-src.uncompressed/commands/{name}.md`