@event4u/agent-config 1.29.0 → 1.32.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/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`

package/.agent-src/skills/copilot-agents-optimization/SKILL.md

@@ -166,7 +166,7 @@ prevent. Fix or remove those BEFORE any dedup/compress work — there's
 no point deduplicating content that is about to be rewritten.
 
 When the drift is severe (whole sections are wrong), recommend
-`/copilot-agents-init` to scaffold a clean replacement rather than
+`/agents init` to scaffold a clean replacement rather than
 patching forever.
 
 ## agent-config Path Conventions — Preserve, Don't "Fix"
@@ -189,7 +189,7 @@ it as "redundant" and never trim its bullets. The patterns it covers:
 If the consumer project's `copilot-instructions.md` is missing the
 section, **add it** during optimization using the canonical block
 from `.augment/templates/copilot-instructions.md`. Surfaces include
-`/copilot-agents init` and `/copilot-agents optimize`.
+`/agents init` and `/agents optimize`.
 
 ## Optimization Checklist
 
@@ -212,7 +212,7 @@ When optimizing either file, check:
 
 ## Related
 
-- **Command:** `/copilot-agents-optimize`
+- **Command:** `/agents optimize`
 - **Skill:** `copilot-config` — Copilot behavior and PR review patterns
 - **Skill:** `agent-docs-writing` — documentation hierarchy
 - **Context:** `augment-infrastructure.md` — full `.augment/` overview

package/.agent-src/skills/error-handling-patterns/SKILL.md

@@ -80,8 +80,8 @@ Exactly **one** layer translates internal errors to the egress format (HTTP stat
 
 ## Procedure: Apply the framework to a new feature
 
-1. List failure modes (each external call, each invariant, each user input class).
-2. Run Step 1 against each, write the classification next to it.
+1. **Inspect** the feature surface — identify every failure mode (each external call, each invariant, each user input class) and write it down.
+2. Run Step 1 of the decision framework against each entry; write the classification next to it.
 3. Pick reporting mechanism per Step 2; reject combinations the language idiom rejects.
 4. For each external call, run Step 3 and write down the chosen resilience strategy.
 5. Sketch the error payload shape (Step 4) and the single boundary (Step 5).

package/.agent-src/skills/feature-planning/SKILL.md

@@ -67,7 +67,7 @@ Explore → Plan → Refine → Roadmap → Implement
 ### Full workflow (complex features, 7 phases)
 
 Use the full workflow for features that span multiple files, require architecture decisions,
-or have unclear requirements. Trigger with `/feature-dev`.
+or have unclear requirements. Trigger with `/feature:dev`.
 
 ```
 Discovery → Exploration → Questions → Architecture → Implementation → Review → Summary
@@ -100,7 +100,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - **Wait for answers before proceeding.**
 
 #### Phase 4: Architecture Design
-- Design 2-3 impl approaches with different tradeoffs:
+- Design 2-3 implementation approaches with different tradeoffs:
   - **Minimal changes** — smallest change, maximum reuse.
   - **Clean architecture** — maintainability, elegant abstractions.
   - **Pragmatic balance** — speed + quality.
@@ -114,7 +114,7 @@ Discovery → Exploration → Questions → Architecture → Implementation →
 - Track progress via task list or roadmap.
 
 #### Phase 6: Quality Review
-- Review the impl for:
+- Review the implementation for:
   - Simplicity, DRY, elegance.
   - Bugs and correctness.
   - Convention adherence.
@@ -136,9 +136,45 @@ Maintain a running **decision log** throughout the planning process. For each de
 Include the decision log in the feature plan file under a `## Decisions` section.
 This ensures future developers (and agents) understand the reasoning, not just the outcome.
 
+## Bite-sized task granularity (structural roadmaps only)
+
+When a feature plan's generated roadmap declares `complexity: structural` in its frontmatter, every task bullet must be self-contained and 2–5 minutes of work. Lightweight roadmaps (the default) skip this section — coarse-grained tasks ("Add login endpoint", "Update tests") are correct when the work is well-scoped and low-risk.
+
+Structural roadmap tasks must include:
+
+1. **Exact file path** — `app/Modules/Auth/Services/LoginService.php`, never *"the login service"*.
+2. **Complete code** — every method body, import, and signature ready to paste; no `// existing code` ellipses, no `…`.
+3. **Exact command** — `php artisan migrate --path=database/migrations/2026_05_09_create_logins.php`, never *"run the migration"*.
+4. **Expected output** — what success looks like (`Migrated: 2026_05_09_create_logins`) and the exit code.
+5. **No placeholders** — angle-bracket placeholders, `TODO`, `FIXME`, `tbd`, and `???` are blockers; resolve before the task ships.
+
+The complexity flag lives in the roadmap's YAML frontmatter:
+
+```yaml
+---
+complexity: structural   # triggers bite-sized granularity
+# or
+complexity: lightweight  # default — skips bite-sized granularity
+---
+```
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Task Structure + § No Placeholders (v5.1.0); complexity-gating is our addition (Council Round 1, Q4 — mitigates UX pushback for senior engineers on well-scoped work).
+
+## Self-review (3-scan checklist)
+
+Before presenting any plan, run these three scans in order. Each is a fast pass — not a deep review. Failures block presentation; fix and re-scan.
+
+1. **Spec coverage** — every requirement, AC bullet, or constraint from the input has a corresponding section / AC / scope item in the plan. Walk the input top-to-bottom; tick each requirement against the plan; missing items become open questions or new AC.
+2. **Placeholder / TODO scan** — grep the draft for `<placeholder>`, `TODO`, `FIXME`, `tbd`, `???`, `XXX`. Either resolve them now or surface them in the *Open questions* section. No placeholder ships unflagged.
+3. **Type / shape consistency** — proposed data structures, API shapes, file paths, and module names match existing codebase patterns. Cite at least one existing file per new structure as the convention anchor.
+
+This scan is **separate from** adversarial-review (below). Self-review catches mechanical gaps (missing AC, leftover placeholders, mis-shaped types); adversarial-review challenges the plan's reasoning.
+
+Source: adapted from `obra/superpowers` `writing-plans/SKILL.md` § Self-Review (v5.1.0).
+
 ## Adversarial self-review
 
-After completing a plan, run the **`adversarial-review`** skill before presenting it.
+After the 3-scan self-review passes, run the **`adversarial-review`** skill before presenting.
 Focus on the "Feature plans / Architecture" attack questions. See that skill for the full process.
 
 ## Feature plan format
@@ -183,7 +219,7 @@ module's `agents/` directory:
 Before creating a feature plan, always:
 1. **Search the codebase** for related code, existing patterns, and affected areas.
 2. **Read module docs** if the feature touches a specific module.
-3. **Check existing features** in `agents/features/` for overlap or deps.
+3. **Check existing features** in `agents/features/` for overlap or dependencies.
 
 ### Be collaborative
 
@@ -194,7 +230,7 @@ Before creating a feature plan, always:
 
 ### Keep it navigational
 
-Feature plans are decision documents, not impl guides.
+Feature plans are decision documents, not implementation guides.
 Implementation details belong in roadmaps.
 
 ## Output format
@@ -221,6 +257,6 @@ Implementation details belong in roadmaps.
 
 - Do NOT create feature plans without user input — always collaborate.
 - Do NOT skip codebase research — always check what exists.
-- Do NOT put impl steps in the feature plan — that's the roadmap's job.
+- Do NOT put implementation steps in the feature plan — that's the roadmap's job.
 - Do NOT commit or push without permission.
 - Do NOT duplicate information from `AGENTS.md` or module docs.