@event4u/agent-config 2.0.0 → 2.2.0

package/.agent-src/commands/fix/{pr-bots.md → pr-bot-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr-bots
+name: fix:pr-bot-comments
 cluster: fix
-sub: pr-bots
+sub: pr-bot-comments
 skills: [php-coder, quality-tools]
 description: Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR
 disable-model-invocation: true
@@ -11,7 +11,7 @@ suggestion:
   trigger_context: "open PR with bot review comments unresolved"
 ---
 
-# /fix pr-bots
+# /fix pr-bot-comments
 ## Input
 
 The user may or may not provide a PR URL.

package/.agent-src/commands/fix/{pr.md → pr-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr
+name: fix:pr-comments
 cluster: fix
-sub: pr
+sub: pr-comments
 skills: [php-coder]
 description: Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR
 disable-model-invocation: true
@@ -11,8 +11,8 @@ suggestion:
   trigger_context: "open PR with unresolved comments (bot + human)"
 ---
 
-# /fix pr
-This command runs `/fix pr-bots` and `/fix pr-developers` in sequence on the same PR.
+# /fix pr-comments
+This command runs `/fix pr-bot-comments` and `/fix pr-developer-comments` in sequence on the same PR.
 
 ## Input
 
@@ -45,14 +45,14 @@ The chosen mode applies to **both** phases.
 
 ### Phase 1: Bot comments
 
-Follow the full `/fix pr-bots` instructions (see `commands/fix/pr-bots.md`).
+Follow the full `/fix pr-bot-comments` instructions (see `commands/fix/pr-bot-comments.md`).
 Use the already-confirmed PR and mode — do not ask again.
 
 Report when done: "Bot comments done. Continuing with reviewer comments..."
 
 ### Phase 2: Developer comments
 
-Follow the full `/fix pr-developers` instructions (see `commands/fix/pr-developers.md`).
+Follow the full `/fix pr-developer-comments` instructions (see `commands/fix/pr-developer-comments.md`).
 Use the same PR and mode.
 
 ### After both phases

package/.agent-src/commands/fix/{pr-developers.md → pr-developer-comments.md}

@@ -1,7 +1,7 @@
 ---
-name: fix:pr-developers
+name: fix:pr-developer-comments
 cluster: fix
-sub: pr-developers
+sub: pr-developer-comments
 skills: [php-coder]
 description: Fix and reply to human reviewer comments on a GitHub PR
 disable-model-invocation: true
@@ -11,7 +11,7 @@ suggestion:
   trigger_context: "open PR with unresolved human-reviewer comments"
 ---
 
-# /fix pr-developers
+# /fix pr-developer-comments
 ## Input
 
 The user may or may not provide a PR URL.

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

@@ -22,9 +22,9 @@ with a single entry point + sub-command dispatch.
 | `/fix refs` | `commands/fix/refs.md` | Find and fix broken cross-references in `.augment/` and `agents/` |
 | `/fix portability` | `commands/fix/portability.md` | Find and fix project-specific references in shared `.augment/` files |
 | `/fix seeder` | `commands/fix/seeder.md` | Scan seeder data files for broken FK references |
-| `/fix pr` | `commands/fix/pr.md` | Fix and reply to **all** open review comments (bots + humans) |
-| `/fix pr-bots` | `commands/fix/pr-bots.md` | Fix and reply to **bot** review comments only |
-| `/fix pr-developers` | `commands/fix/pr-developers.md` | Fix and reply to **human** reviewer comments only |
+| `/fix pr-comments` | `commands/fix/pr-comments.md` | Fix and reply to **all** open review comments (bots + humans) |
+| `/fix pr-bot-comments` | `commands/fix/pr-bot-comments.md` | Fix and reply to **bot** review comments only |
+| `/fix pr-developer-comments` | `commands/fix/pr-developer-comments.md` | Fix and reply to **human** reviewer comments only |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -41,9 +41,9 @@ Sub-command names match the locked contract in
    > 2. refs — fix broken cross-refs in agent docs
    > 3. portability — purge project-specific refs from shared package
    > 4. seeder — scan seeders for broken FK references
-   > 5. pr — address all open review comments
-   > 6. pr-bots — address bot reviewer comments only
-   > 7. pr-developers — address human reviewer comments only
+   > 5. pr-comments — address all open review comments
+   > 6. pr-bot-comments — address bot reviewer comments only
+   > 7. pr-developer-comments — address human reviewer comments only
 
 ## Rules
 

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).
 
@@ -12,7 +12,7 @@ this file mirrors that contract for runtime lookup. Linter:
 
 | 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` |
+| `/fix` | 1 | `ci` · `pr-comments` · `pr-bot-comments` · `pr-developer-comments` · `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`                                                   |
 | `/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`                                 |

package/.agent-src/rules/no-cheap-questions.md

@@ -20,9 +20,17 @@ NEVER OFFER NUMBERED CHOICES WITHOUT A REAL TRADE-OFF.
 
 ## What counts as cheap
 
-Nine classes — sequencing · format-only · commit asks (forbidden by [`commit-policy`](commit-policy.md)) · CI / test asks ([`verify-before-complete`](verify-before-complete.md) decides) · fenced-step re-asks ([`scope-control § fenced step`](scope-control.md#fenced-step--user-set-review-gates)) · Iron-Law option (breaches `commit-policy`, `scope-control § git-ops`, or `non-destructive-by-default`) · context-derived · dominant option · re-ask after decline ([`scope-control § decline = silence`](scope-control.md#decline--silence--no-re-asking-on-the-same-task)).
+Ten classes — sequencing · format-only · commit asks · CI / test asks · fenced-step re-asks · Iron-Law option · context-derived · dominant option · re-ask after decline · **paternalistic state-assuming option** (Iron Law 3 below). Per-class detail + governing rule: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
 
-Per-class patterns and examples: [`asking-and-brevity-examples § cheap-question-catalog`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#cheap-question-class-catalog--extended-examples).
+## Iron Law 3 — No Paternalistic State-Assuming Options
+
+```
+NEVER FABRICATE USER STATE TO JUSTIFY AN OPTION.
+"TAKE A BREAK", "SLEEP ON IT", "COME BACK FRESH" — FORBIDDEN.
+THE USER DECIDES WHEN TO STOP. THE AGENT DECIDES WHAT TO BUILD NEXT.
+```
+
+Every numbered option = technical / scope / sequencing choice with real trade-off, not mood-management nudge. Forbidden patterns + carve-outs: [`asking-and-brevity-examples § iron-law-3`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md#no-cheap-questions--iron-law-3-detail-paternalistic-state-options).
 
 ## Pre-Send Self-Check — MANDATORY before every question
 
@@ -34,6 +42,7 @@ Run silently before any numbered-options block:
 4. One option obviously dominant?
 5. User fenced next step (*"plan only"*, *"review first"*) → deliver + handback per `scope-control § fenced step`.
 6. User already declined? Re-ask forbidden per `scope-control § decline = silence`.
+7. Any option assumes user fatigue / frustration / "had enough" without in-message citation? Iron Law 3 — drop it.
 
 Any "yes" → **do not ask**. Pick the dominant path, state assumption inline (*"assuming X — adjust if wrong"*), hand back. One-question-per-turn from [`ask-when-uncertain`](ask-when-uncertain.md) still applies when the question is genuine.
 

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

@@ -146,6 +146,30 @@ install, first example, or requirements.
 deep-link-table pattern, collapsibles, and anti-patterns (premature
 splitting, duplication between README and `/docs/`).
 
+#### Per-AI catalog pattern (multi-platform AI / CLI packages)
+
+For packages targeting many AI assistants or platforms (CLI installers,
+agent-config tools, language SDKs with 10+ targets), prefer flat per-AI
+catalog over giant matrix. One line per target, install command on left,
+aligned trailing comment naming platform:
+
+```bash
+npx <package> init --tools=claude-code      # Claude Code
+npx <package> init --tools=cursor           # Cursor
+npx <package> init --tools=windsurf         # Windsurf
+# ... one line per supported target
+```
+
+Pair catalog with separate "Global install" subsection (same flags plus
+`--global`) and "Other commands" subsection. Reference example:
+[`README.md § Pick specific AIs`](../../../README.md#pick-specific-ais) in
+this repo. Inspiration:
+[`ui-ux-pro-max-skill § Installation`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill#installation).
+
+Use catalog when package's primary install action varies by platform; use
+matrix table (Tool / Rules / Skills / Commands) for capability comparison.
+Different jobs — install vs. coverage.
+
 README = enough to adopt. Docs = enough to master.
 
 ### 8. Validate

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": "2.0.0"
+    "version": "2.2.0"
   },
   "plugins": [
     {
@@ -112,9 +112,9 @@
         "./.claude/skills/fix",
         "./.claude/skills/fix-ci",
         "./.claude/skills/fix-portability",
-        "./.claude/skills/fix-pr",
-        "./.claude/skills/fix-pr-bots",
-        "./.claude/skills/fix-pr-developers",
+        "./.claude/skills/fix-pr-bot-comments",
+        "./.claude/skills/fix-pr-comments",
+        "./.claude/skills/fix-pr-developer-comments",
         "./.claude/skills/fix-refs",
         "./.claude/skills/fix-seeder",
         "./.claude/skills/flux",

package/CHANGELOG.md

@@ -9,6 +9,23 @@ versioning policy is documented in [CONTRIBUTING.md](CONTRIBUTING.md#versioning-
 
 ## [Unreleased]
 
+Four roadmaps land in this release.
+
+**Global-First Install (R4)** — `npx @event4u/create-agent-config init`
+now defaults to a **global** install (`~/.claude/`, `~/.cursor/`, …)
+when run outside a project, and a **project** install when run inside
+one. A new global lockfile at `~/.config/agent-config/installed.lock`
+records `agent_config_version` + `tools[]` and refuses mismatched
+re-installs (exit 1) until `update` or `--force` realigns it. New
+`agent-config export --tool=<id> --output=<path>` subcommand ejects a
+named tool's resolved content into the project tree (idempotent;
+`--force` overrides drift). 12 supported tool ids (claude-code,
+cursor, windsurf, cline, aider, codex, gemini, copilot,
+claude-desktop, continue, kilocode, zed, jetbrains, kiro). Windows
+CI matrix added for the lockfile + export paths. See
+[`docs/decisions/ADR-007-agent-discovery-scopes.md`](docs/decisions/ADR-007-agent-discovery-scopes.md)
+and [`docs/decisions/ADR-008-installed-tools-manifest.md`](docs/decisions/ADR-008-installed-tools-manifest.md).
+
 Three roadmaps land in this release.
 
 **Universal Execution Engine (R1)** — the `/implement-ticket` runtime is
@@ -318,6 +335,68 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [2.2.0](https://github.com/event4u-app/agent-config/compare/2.1.0...2.2.0) (2026-05-12)
+
+### Features
+
+* **npx:** expand --tools validator to 13 supported AI ids ([7af69a7](https://github.com/event4u-app/agent-config/commit/7af69a766f575c30d8f29ea04052647b6a1b8a19))
+* **cli:** add sync and validate subcommands for installed-tools manifest ([62a5c66](https://github.com/event4u-app/agent-config/commit/62a5c66a131bcf8866be2a8c0e76ba6e054017af))
+* **cli:** add export subcommand and update version-drift handling ([6110f3b](https://github.com/event4u-app/agent-config/commit/6110f3b0ee454ca215c569d8f42ca38ffce577e8))
+* **install:** global-first install with lockfile + installed-tools manifest engine ([6200d42](https://github.com/event4u-app/agent-config/commit/6200d42225d5712a10d5458dc608da3f5cd0164c))
+
+### Bug Fixes
+
+* **rules:** trim no-cheap-questions to satisfy 12% concentration cap ([4abf946](https://github.com/event4u-app/agent-config/commit/4abf94628838c027da13d190e5e7b27738070db2))
+
+### Documentation
+
+* **rules:** add no-cheap-questions Iron Law 3 against paternalistic state options ([b98687b](https://github.com/event4u-app/agent-config/commit/b98687bd397d39eae6811e54eb743a095fa33b8b))
+* README + installation + manifest guideline for global-first install ([cdc52ff](https://github.com/event4u-app/agent-config/commit/cdc52ffc5abb9cff6fda9133dd0b8dc524794d18))
+* **contracts:** add tier-3 contrib plugin contract ([2dbf9cd](https://github.com/event4u-app/agent-config/commit/2dbf9cd2ec772dc2248de2b8f17248e97a67a60b))
+* **adr:** add ADR-007 global-first install + ADR-008 installed-tools manifest ([e214de2](https://github.com/event4u-app/agent-config/commit/e214de27bd8d19858fdc16cecc4ebfeaaebce136))
+
+### CI
+
+* **windows:** add lockfile + export tests on Windows runner ([e5802a5](https://github.com/event4u-app/agent-config/commit/e5802a56f45bcfd5eb845c7af816bb12a0b4492b))
+
+### Chores
+
+* **taskfile:** add test-install-local for offline one-liner smoke test ([594ac69](https://github.com/event4u-app/agent-config/commit/594ac69c8682f106dee9ebc9ce3e55bb0083e254))
+* **roadmap:** archive road-to-global-first-install (24/24 complete) ([71d8cf2](https://github.com/event4u-app/agent-config/commit/71d8cf2966976c286ffecc1646cb7990255cccd1))
+
+Tests: 3350 (+97 since 2.1.0)
+
+## [2.1.0](https://github.com/event4u-app/agent-config/compare/2.0.0...2.1.0) (2026-05-12)
+
+### Features
+
+* **wrapper:** add npx fallback and sanitize wrapper error test ([9f4326b](https://github.com/event4u-app/agent-config/commit/9f4326bffc59d79e4421b0cd8966c99348afe1e6))
+* **installer:** add source-repo guard and drop composer/global paths ([5388de2](https://github.com/event4u-app/agent-config/commit/5388de2598ea668a8671f49bd7bacd4866ed1c33))
+
+### Documentation
+
+* **installation:** add Upgrading from v1 section ([f35df4b](https://github.com/event4u-app/agent-config/commit/f35df4b9667eb848ce2ec47f4a7c550b1bba4054))
+* align install guides with v2 npx-only flow ([e841a14](https://github.com/event4u-app/agent-config/commit/e841a14cdbb6691433976c57ff9b28b3ec4992ad))
+* **readme:** collapse plugin-install table to one-liner ([b3407bb](https://github.com/event4u-app/agent-config/commit/b3407bb2fda39a8a57c0e2f72c8b430bed4fd012))
+
+### Refactoring
+
+* **cli:** rename fix:pr sub-commands for clarity ([fbdf636](https://github.com/event4u-app/agent-config/commit/fbdf636a50a06f3b35fe5c3d5fb108e9c15e6266))
+
+### Tests
+
+* **install:** drop composer-detection tests retired in v2 ([e37ad99](https://github.com/event4u-app/agent-config/commit/e37ad99beaebbb5f6a98b41e02ecefd6b0d39453))
+
+### Build
+
+* **tasks:** add npm:login + npm:publish-installer ([22639f8](https://github.com/event4u-app/agent-config/commit/22639f877feee33a3cbadb9147941cfb32fb6c9e))
+
+### Chores
+
+* remove retired setup.sh and global-install test surface ([3eebcf7](https://github.com/event4u-app/agent-config/commit/3eebcf72bcc45af168df4fd4b172a2484901a793))
+
+Tests: 3253 (-4 since 2.0.0)
+
 ## [2.0.0](https://github.com/event4u-app/agent-config/compare/1.41.2...2.0.0) (2026-05-12)
 
 ### BREAKING CHANGES

package/README.md

@@ -14,7 +14,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>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>69 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>174 Skills</strong> · <strong>60 Rules</strong> · <strong>106 Commands</strong> · <strong>70 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -36,6 +36,14 @@ If none of those apply yet — start with the [Quickstart](#quickstart) and pick
 Two minutes from `npx` to a better-behaved agent — no install, no
 vendored package, no postinstall hook.
 
+**v2.1+ — global-first by default.** Running `init` outside a project
+defaults to a user-scope install (`~/.claude/`, `~/.cursor/`, …) and
+records itself in `~/.config/agent-config/installed.lock`. Running it
+inside a project (a `package.json` / `composer.json` / `pyproject.toml`
+manifest is present) defaults to a project-scope install. Override with
+`--scope=global` or `--scope=project`. See
+[`docs/installation.md`](docs/installation.md) for the full matrix.
+
 ### For teams (recommended)
 
 Run once in the project root — `npx` resolves the runtime against the
@@ -77,15 +85,56 @@ Copilot fallback) is wired through one universal dispatcher per
 `--format json` for tooling). The installer also dry-fires the
 dispatcher per bridge as a post-install smoke test (skip: `--no-smoke`).
 
+### Pick specific AIs
+
+Default `init` wires every supported AI. To install just one, pass
+`--tools=<name>`:
+
+```bash
+npx @event4u/agent-config init --tools=claude-code      # Claude Code
+npx @event4u/agent-config init --tools=cursor           # Cursor
+npx @event4u/agent-config init --tools=windsurf         # Windsurf
+npx @event4u/agent-config init --tools=cline            # Cline
+npx @event4u/agent-config init --tools=gemini-cli       # Gemini CLI
+npx @event4u/agent-config init --tools=copilot          # GitHub Copilot
+npx @event4u/agent-config init --tools=augment          # Augment Code
+npx @event4u/agent-config init --tools=roocode          # Roo Code
+npx @event4u/agent-config init --tools=aider            # Aider
+npx @event4u/agent-config init --tools=codex            # Codex CLI
+npx @event4u/agent-config init --tools=claude-desktop   # Claude Desktop
+npx @event4u/agent-config init --tools=continue         # Continue
+```
+
+Multiple AIs in one shot: `--tools=claude-code,cursor,augment`.
+
+#### Global install (user-scope, available across projects)
+
+Add `--global` to write to the user-scope paths from
+[`ADR-007`](docs/decisions/ADR-007-agent-discovery-scopes.md) (`~/.claude/`,
+`~/.cursor/`, …) instead of the current project:
+
+```bash
+npx @event4u/agent-config init --global                       # all tools, user-scope
+npx @event4u/agent-config init --tools=claude-code --global   # → ~/.claude/
+npx @event4u/agent-config init --tools=cursor --global        # → ~/.cursor/
+```
+
+Per-AI scope support varies — Claude Desktop, for example, is
+global-only (no project-local discovery on macOS), while Roo Code and
+Continue.dev are project-local. The Supported Tools table below
+documents per-AI scope. Incompatible combinations (e.g.
+`--tools=roocode --global` or `--tools=claude-desktop` without
+`--global`) are rejected with a directive error; `--tools=all`
+silently filters to the scope's compatible subset.
+
 ### For individual use (optional)
 
-Install directly in your agent for global, cross-project use:
+Skills-only, global across projects — installs into the agent itself,
+no per-repo `init`:
 
-| Tool | Install |
-|---|---|
-| **Augment CLI** | `auggie plugin install agent-config@event4u-agent-config` |
-| **Claude Code** | `claude plugin install agent-config@event4u-agent-config` |
-| **Copilot CLI** | `copilot plugin install agent-config@event4u-agent-config` |
+```bash
+<auggie|claude|copilot> plugin install agent-config@event4u-agent-config
+```
 
 → [All install options & project bridge setup](docs/installation.md)
 
@@ -432,16 +481,31 @@ Every developer gets the same behavior. No per-user setup needed —
 | **Windsurf** | ✅ | — | ☑️ | Reads `.windsurfrules` + commands via AGENTS.md |
 | **Gemini CLI** | ✅ | — | ☑️ | Reads `GEMINI.md` (includes commands reference) |
 | **GitHub Copilot** | ✅ | — | ☑️ | Reads `.github/copilot-instructions.md` (includes commands) |
+| **Roo Code** | ✅ | — | ☑️ | Auto-discovers `.roo/rules/*.md` + AGENTS.md |
+| **Codex CLI** | ✅ | — | ☑️ | Auto-discovers `AGENTS.md` at project root |
+| **Continue.dev** | ✅ | — | ☑️ | Auto-discovers `.continue/rules/*.md` + AGENTS.md |
+| **Aider** | 📌 | — | — | Marker + manual `read:` in `.aider.conf.yml` |
+| **Claude Desktop** | 📌 | — | — | Global-only — install with `--global` (see ADR-007) |
 
 ✅ = native support &nbsp; — = not available &nbsp; ☑️ = text reference only
-(commands are listed in `AGENTS.md`, but the tool cannot invoke them as
-native slash-commands)
+(commands listed in `AGENTS.md`, tool cannot invoke them as native
+slash-commands) &nbsp; 📌 = informational marker only (no auto-discovery
+or manual wiring required)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
 > package (rules + 174 skills + 106 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.
+> Gemini CLI, GitHub Copilot, Roo Code, Codex CLI, and Continue.dev only get
+> the **rules** natively; skills and commands are available as documentation
+> the agent can read, not as first-class features. Aider and Claude Desktop
+> ship marker-only bridges — Aider needs a one-line `read:` entry in
+> `.aider.conf.yml`; Claude Desktop is global-scope and pairs with `--global`.
+
+> **Team reproducibility (ADR-008):** every tool you `init` is also recorded in
+> `agents/installed-tools.lock` — committed, machine-managed. New team members
+> run `npx @event4u/agent-config sync` after cloning and every bridge in the
+> table above is replayed locally. CI can gate drift with `agent-config validate`.
+> Schema, workflow, and drift catalog:
+> [`docs/guidelines/agent-infra/installed-tools-manifest.md`](docs/guidelines/agent-infra/installed-tools-manifest.md).
 
 ### Plugin-installed (optional, for global use)
 

package/docs/architecture.md

@@ -54,7 +54,7 @@ tree where:
   `.agent-src/<subdir>/`. Reading a context follows the symlink to
   the package payload.
 - `.augment/docs/guidelines/` — **symlink** into the package's
-  `docs/guidelines/` (consumer side: `vendor/event4u/agent-config/docs/guidelines/`;
+  `docs/guidelines/` (consumer side: `node_modules/@event4u/agent-config/docs/guidelines/`;
   package self-projection: `../docs/guidelines/`). This is the only
   `docs/` subdirectory exposed in `.augment/`; `docs/contracts/` and
   `docs/decisions/` are package-internal — rules that reference
@@ -145,7 +145,7 @@ fails on any source-side violation, without producing artifacts.
 | **Skills** | 174 | 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** | 106 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 69 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Guidelines** | 70 | 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

@@ -294,9 +294,9 @@ are excluded.
 | command | [`feature`](../.agent-src/commands/feature.md) | cluster: feature | Feature orchestrator — routes to explore, plan, refactor, roadmap, dev |
 | command | [`fix:ci`](../.agent-src/commands/fix/ci.md) | cluster: fix | Fetch CI errors from GitHub Actions and fix them |
 | command | [`fix:portability`](../.agent-src/commands/fix/portability.md) | cluster: fix | Find and fix project-specific references in shared .augment/ package files |
-| command | [`fix:pr-bots`](../.agent-src/commands/fix/pr-bots.md) | cluster: fix | Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR |
-| command | [`fix:pr-developers`](../.agent-src/commands/fix/pr-developers.md) | cluster: fix | Fix and reply to human reviewer comments on a GitHub PR |
-| command | [`fix:pr`](../.agent-src/commands/fix/pr.md) | cluster: fix | Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR |
+| command | [`fix:pr-bot-comments`](../.agent-src/commands/fix/pr-bot-comments.md) | cluster: fix | Fix and reply to bot review comments (Copilot, Augment, Greptile, etc.) on a GitHub PR |
+| command | [`fix:pr-comments`](../.agent-src/commands/fix/pr-comments.md) | cluster: fix | Fix and reply to all open review comments (bots + human reviewers) on a GitHub PR |
+| command | [`fix:pr-developer-comments`](../.agent-src/commands/fix/pr-developer-comments.md) | cluster: fix | Fix and reply to human reviewer comments on a GitHub PR |
 | command | [`fix:refs`](../.agent-src/commands/fix/refs.md) | cluster: fix | Find and fix broken cross-references in .augment/ and agents/ files |
 | command | [`fix:seeder`](../.agent-src/commands/fix/seeder.md) | cluster: fix | Scan seeder data files for broken foreign key references — find constants used without getReference() and fix them |
 | command | [`fix`](../.agent-src/commands/fix.md) | cluster: fix | Fix orchestrator — routes to ci, references, portability, seeder, pr-comments, pr-bot-comments, pr-developer-comments |

package/docs/contracts/command-clusters.md

@@ -11,7 +11,7 @@ stability: beta
 The agent-config command surface collapses related atomic commands
 into **verb clusters**. A cluster is a single top-level command
 (e.g. `/fix`) that dispatches to sub-commands (e.g. `/fix ci`,
-`/fix pr`). Old atomic commands stay one release as deprecation
+`/fix pr-comments`). Old atomic commands stay one release as deprecation
 shims, then disappear.
 
 This file is the **locked source of truth** for which clusters
@@ -27,7 +27,7 @@ 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` |
+| `fix` | 1 | `ci` · `pr-comments` · `pr-bot-comments` · `pr-developer-comments` · `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-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 |
@@ -84,7 +84,7 @@ every new sub-command added to an existing cluster.
    cluster's primary verb (e.g. `/roadmap:create` + `process-*`
    composites).
 
-3. **Sub-name format.** kebab-case (`pr-bots`, `process-phase`),
+3. **Sub-name format.** kebab-case (`pr-bot-comments`, `process-phase`),
    ≤ 24 chars, no leading verb that duplicates the cluster name
    (use `/fix:ci`, not `/fix:fix-ci`).
 

package/docs/contracts/file-ownership-matrix.json

@@ -261,19 +261,19 @@
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr-bots.md": {
+    ".agent-src.uncompressed/commands/fix/pr-bot-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr-developers.md": {
+    ".agent-src.uncompressed/commands/fix/pr-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
       "load_context_eager": []
     },
-    ".agent-src.uncompressed/commands/fix/pr.md": {
+    ".agent-src.uncompressed/commands/fix/pr-developer-comments.md": {
       "kind": "command",
       "rule_type": null,
       "load_context": [],
@@ -3088,22 +3088,22 @@
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr-bots.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr-bots.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-bot-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-bot-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr-developers.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr-developers.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0
     },
     {
-      "source": ".agent-src.uncompressed/commands/fix/pr.md",
-      "target": ".agent-src.uncompressed/commands/fix/pr.md",
+      "source": ".agent-src.uncompressed/commands/fix/pr-developer-comments.md",
+      "target": ".agent-src.uncompressed/commands/fix/pr-developer-comments.md",
       "type": "WRITE",
       "via": "self",
       "depth": 0