@event4u/agent-config 2.0.0 → 2.2.0

package/docs/guidelines/agent-infra/installed-tools-manifest.md

@@ -0,0 +1,135 @@
+# Installed-Tools Manifest
+
+Project-committed bill of materials for AI tooling. Answers the
+question "which AIs does this project use, where do their bridges live,
+and is everyone on the team on the same set?". Canonical schema is
+ADR-008 ([`docs/decisions/ADR-008-installed-tools-manifest.md`](../../decisions/ADR-008-installed-tools-manifest.md)).
+Phase 3 of [`road-to-global-first-install`](../../../agents/roadmaps/road-to-global-first-install.md).
+
+This file lives at **`agents/installed-tools.lock`** — committed,
+machine-managed, and orthogonal to `.agent-project-settings.yml`
+(which owns *behaviour*, not *bill of materials*).
+
+## Schema (v1)
+
+```yaml
+schema_version: 1
+agent_config_version: "2.x.y"          # last package version that wrote the file
+tools:
+  - name: claude-code                  # must match _VALID_TOOLS in scripts/install.py
+    scope: global                      # one of: global, project
+    bridge_marker: ~/.claude/          # validate checks this path exists
+    installed_at: "2026-05-12"
+  - name: roocode
+    scope: project                     # workspace-wins → must live in repo
+    bridge_marker: .roo/rules/agent-config.md
+    installed_at: "2026-05-12"
+```
+
+| Field | Owner | Notes |
+|---|---|---|
+| `schema_version` | machine | bumps on breaking schema changes |
+| `agent_config_version` | machine | last writer's package version; `validate` flags drift |
+| `tools[]` | machine | append-on-init order preserved (not alphabetised) |
+| `tools[].name` | machine | one of the 17 valid IDs in `scripts/install.py` |
+| `tools[].scope` | machine | `global` (user-home) or `project` (workspace bridge) |
+| `tools[].bridge_marker` | machine | absolute / `~`-prefixed for global, repo-relative for project |
+| `tools[].installed_at` | machine | ISO date; informational only |
+
+The file is **machine-managed**. Hand-editing is discouraged — every
+mutation goes through `init`, `sync`, or `init --force`.
+
+## Workflow
+
+### Team onboarding (clone → sync → done)
+
+```bash
+git clone <repo>
+cd <repo>
+npx @event4u/agent-config sync
+```
+
+`sync` reads `agents/installed-tools.lock`, checks every listed tool's
+bridge marker, and replays `install.py --tools=<id>` for each missing
+one. Tools whose marker is already present are skipped — `sync` is
+idempotent and safe to re-run.
+
+### Adding a tool
+
+```bash
+npx @event4u/agent-config init --tools=<id>
+# or --tools=<id1>,<id2>
+```
+
+`init` writes an entry per tool. Existing entry with the same
+`(name, scope)` → no-op. Entry with **different scope** → loud warning
+and refusal until you pass `--force` (see scope migration below).
+
+### Drift detection (CI gate)
+
+```bash
+npx @event4u/agent-config validate
+```
+
+Read-only. Exit code 1 if any drift is found. Surfaces three drift
+kinds; no auto-fix.
+
+| Kind | Trigger | Fix |
+|---|---|---|
+| `marker_missing` | recorded `bridge_marker` does not exist | `agent-config sync` |
+| `scope_divergence` | marker only exists at the *other* scope | `agent-config init --tools=<id> --force` |
+| `version_drift` | manifest's `agent_config_version` ≠ installed package | `agent-config update` then `agent-config init --force` |
+
+`--skip-version-check` suppresses the third kind for repositories that
+intentionally pin an older version of the manifest.
+
+## Scope migration
+
+Moving a tool between `project` and `global` is supported but loud:
+
+1. Run `init --tools=<id> --scope=<new> --force`. The installer detects
+   the conflict, warns, and rewrites the entry only when `--force` is
+   present.
+2. The old bridge is **not** removed automatically — clean up the
+   leftover marker yourself (`rm .windsurf/agent-config.md` etc.).
+3. `validate` afterwards confirms the new state.
+
+Reasoning: scope is a project-wide decision; flipping it silently
+would surprise other team members who never asked for the change. The
+loud refusal forces an explicit `--force` so the diff is reviewable in
+the next commit.
+
+## Relationship to other files
+
+| File | What it answers | Layer |
+|---|---|---|
+| `agents/installed-tools.lock` | **which AIs?** (this guideline) | bill of materials |
+| `.agent-project-settings.yml` | **how do agents behave?** | layered-settings (team file) |
+| `~/.config/agent-config/installed.lock` | **which package version did I install globally?** | per-developer global lockfile (Phase 1) |
+| `.agent-settings.yml` | **what are my personal preferences in this project?** | layered-settings (developer file) |
+
+Each file has one job. They never overlap. The two `.lock` files look
+similar by name but answer different questions: `installed.lock` is
+per-developer / cross-project (the package itself), while
+`installed-tools.lock` is per-project / team-shared (which tools are
+expected in *this* repo).
+
+## CI integration
+
+Recommended gate (GitHub Actions / GitLab CI):
+
+```yaml
+- name: Validate installed-tools manifest
+  run: npx @event4u/agent-config validate
+```
+
+Pair it with `agent-config sync` in your dev-setup script so new
+contributors get a working environment without reading the manifest by
+hand.
+
+## References
+
+- [`ADR-008`](../../decisions/ADR-008-installed-tools-manifest.md) — manifest decision and schema.
+- [`ADR-007`](../../decisions/ADR-007-agent-discovery-scopes.md) — global-first install (prerequisite).
+- [`docs/installation.md`](../../installation.md) — team-onboarding flow.
+- [`layered-settings.md`](layered-settings.md) — parallel settings hierarchy (orthogonal to this manifest).

package/docs/installation.md

@@ -1,7 +1,32 @@
 # Installation
 
-**Principle:** Project-installed by default, plugin-enhanced when available.
-No Task, no Make, no build tools required for installation.
+**Principle:** Global-first install (cross-project, in `~/.claude/`,
+`~/.cursor/`, …), opt-in project export when a team wants the config
+committed to a repo. No Task, no Make, no build tools required.
+
+> **v2.1+** — the installer detects intent. Running `npx
+> @event4u/create-agent-config init` in `~/` or any directory without a
+> project manifest defaults to **global**. Running it inside a project
+> (`package.json` / `composer.json` / `pyproject.toml` / etc.) defaults
+> to **project**. Pass `--scope=global` or `--scope=project` to override
+> detection. See `--scope` in the CLI help for the full matrix.
+
+A global install records itself in `~/.config/agent-config/installed.lock`
+(schema_version, agent_config_version, installed_at, tools[]). `npx
+@event4u/create-agent-config update` keeps that manifest in lockstep
+with the project pin in `.agent-settings.yml`. A version-mismatched
+re-run of `init --scope=global` is refused with exit code 1 until you
+`update` or pass `--force`.
+
+To commit a specific tool's config into a project repo, use:
+
+```bash
+agent-config export --tool=<id> --output=<path>
+```
+
+(Idempotent; `--force` overrides drift. `--list` enumerates supported
+tool ids. See [`docs/contracts/command-clusters.md`](contracts/command-clusters.md)
+for the export contract.)
 
 ## Per-IDE setup — quick index
 
@@ -31,6 +56,41 @@ Combine surfaces by comma-separating: `--tools=claude-code,cursor,windsurf`.
 
 ---
 
+## Upgrading from v1
+
+v2 is a breaking change: the local-install scheme (Composer
+`require-dev`, npm `devDependency`, the `--global` symlink namespace
+under `~/.claude/`, `~/.cursor/`, `~/.codeium/windsurf/`,
+`~/.config/agent-config/`) is **retired**. v2 is npx-only — the
+runtime is resolved per invocation, pinned by
+`agent_config_version` in `.agent-settings.yml`.
+
+One command does the cutover, idempotently:
+
+```bash
+./agent-config migrate              # remove legacy install signals
+./agent-config migrate --dry-run    # detect only, no writes
+```
+
+What `migrate` cleans up:
+
+| What | Action |
+|---|---|
+| `package.json` → `devDependencies.@event4u/agent-config` | Removed (lockfile updated on next `npm install`). |
+| `composer.json` → `require*.event4u/agent-config` | Removed (lockfile updated on next `composer update`). |
+| Symlinks `.augment/`, `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` pointing into `vendor/` or `node_modules/` | Deleted. User-owned links are preserved with a warning. |
+| `.agent-settings.yml` | Written fresh if missing, with `agent_config_version` pinned. |
+| `.gitignore` agent-config block | Refreshed. |
+
+After `migrate` runs, you can drop the now-unreferenced
+`node_modules/@event4u/agent-config/` and `vendor/event4u/agent-config/`
+directories with `npm prune` and `composer update` respectively.
+
+Full contract sketch + the retired `--global` namespace teardown:
+[`docs/migration/v1-to-v2.md`](migration/v1-to-v2.md).
+
+---
+
 ## Mechanisms reference
 
 The rest of this page documents the underlying install mechanisms
@@ -46,9 +106,9 @@ the per-IDE index above.
 > 2. `scripts/install.py` — bridge files (`.agent-settings.yml`, VSCode /
 >    Augment / Copilot JSON descriptors).
 >
-> `bin/install.php` and `scripts/postinstall.sh` are thin wrappers that
-> delegate to `scripts/install`. Both underlying stages remain callable
-> directly for advanced use; see their `--help`.
+> `npx @event4u/create-agent-config init` and `setup.sh` (curl-based)
+> are thin wrappers that delegate to `scripts/install`. Both underlying
+> stages remain callable directly for advanced use; see their `--help`.
 >
 > Python 3.10+ is required for bridges. If it is missing, the orchestrator
 > prints a warning and continues with the payload sync only.
@@ -80,9 +140,9 @@ the per-IDE index above.
 ## Quickstart — one-liner entrypoints
 
 Try `@event4u/agent-config` in any directory in under 30 seconds, without
-`composer require` or `git clone` first. Both entrypoints are thin
-wrappers around `scripts/install` — same payload, same flags, no extra
-state.
+adding it as a dev dependency or cloning the repo first. Both
+entrypoints are thin wrappers around `scripts/install` — same payload,
+same flags, no extra state.
 
 ### `npx` (Node ≥ 18)
 
@@ -139,41 +199,26 @@ used. Pass `--yes` (or `-y`) to force non-interactive mode anywhere.
 Install once in the project — available to everyone working on it.
 The package is versioned with the project. Settings are committed once.
 
-### Composer (PHP projects)
+### npx (recommended for any project)
 
 ```bash
-composer require --dev event4u/agent-config
-php vendor/bin/install.php
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 ```
 
-Composer does **not** run a post-install hook for this package — the
-installer is an explicit step. `bin/install.php` is a thin wrapper that
-calls `scripts/install` (the bash orchestrator). To pick a non-default
-profile:
+The wrapper downloads the latest `@event4u/agent-config` tarball into a
+temp dir, runs `scripts/install` with the selected tools, and cleans up
+afterwards. Nothing is added to `package.json`.
 
-```bash
-php vendor/bin/install.php --profile=balanced
-```
-
-The `--profile` flag controls the initial `cost_profile` value written
-to `.agent-settings.yml`.
-
-### npm (JavaScript/TypeScript projects)
+### Global CLI (one install per machine)
 
 ```bash
-npm install --save-dev @event4u/agent-config
+npm install -g @event4u/agent-config
+agent-config --help
 ```
 
-npm runs `scripts/postinstall.sh` automatically, which invokes
-`scripts/install` — the same orchestrator every other entry point uses.
-
-If your setup disables install scripts (`npm config set ignore-scripts
-true` or similar), nothing happens and the command prints no warning.
-Re-run the installer manually in that case:
-
-```bash
-bash node_modules/@event4u/agent-config/scripts/install
-```
+The global install puts `agent-config` on `$PATH` so the project
+wrapper (`./agent-config`) can fall through to it when no
+`node_modules/@event4u/agent-config/` exists.
 
 ### Installer orchestrator (`scripts/install`)
 
@@ -188,12 +233,6 @@ bash scripts/install --skip-sync      # bridges only
 bash scripts/install --dry-run        # show payload sync plan, skip bridges
 ```
 
-PHP users can use the Composer wrapper, which forwards all flags:
-
-```bash
-php vendor/bin/install.php --profile=balanced
-```
-
 Under the hood:
 
 - `scripts/install.sh` — payload sync (callable directly for sync-only runs).
@@ -234,6 +273,7 @@ After initial setup, commit these files:
 
 ```
 .agent-settings.yml                ← shared profile (e.g., cost_profile: minimal)
+agents/installed-tools.lock        ← AI bill of materials (ADR-008, Phase 3)
 .augment/                          ← rules, skills, commands (symlinks)
 .cursor/rules/                     ← Cursor rules (symlinks)
 .claude/                           ← Claude rules, skills (symlinks)
@@ -241,7 +281,37 @@ AGENTS.md                          ← Copilot/Gemini instructions
 .github/copilot-instructions.md   ← GitHub Copilot instructions
 ```
 
-New team members: run `composer install` (or `npm install`) → open editor → done.
+`agents/installed-tools.lock` lists every AI tool the project expects,
+its scope (`global` or `project`), and its bridge marker path. Written
+by `init`, replayed by `sync`, checked by `validate`. Schema and
+workflow: [`docs/guidelines/agent-infra/installed-tools-manifest.md`](guidelines/agent-infra/installed-tools-manifest.md).
+
+### Team onboarding — clone → sync → done
+
+New team members get every AI bridge online with a single command:
+
+```bash
+git clone <repo>
+cd <repo>
+npx @event4u/agent-config sync
+```
+
+`sync` reads `agents/installed-tools.lock` and re-runs the installer
+for every tool whose bridge marker is missing locally. Idempotent —
+re-running after every clone is safe. Tools with markers already in
+place are skipped.
+
+Pair it with a CI gate to catch drift in PRs:
+
+```bash
+npx @event4u/agent-config validate
+```
+
+`validate` is read-only. Exit 1 on any of: marker missing, scope
+divergence (manifest says `project` but marker only exists at the
+global anchor, or vice versa), version drift (manifest's
+`agent_config_version` ≠ installed package). Full drift catalog and
+fix table: [`installed-tools-manifest.md § Drift detection`](guidelines/agent-infra/installed-tools-manifest.md#drift-detection-ci-gate).
 
 ---
 
@@ -544,15 +614,12 @@ for the upgrade path.
 When a new version of the package is published:
 
 ```bash
-composer update event4u/agent-config
-php vendor/bin/install.php          # refresh bridges + symlinks
-```
+# npx (one-shot, recommended) — always uses the latest tarball
+npx @event4u/create-agent-config init --tools=claude-code,cursor
 
-Or for npm projects:
-
-```bash
-npm update @event4u/agent-config
-bash node_modules/@event4u/agent-config/scripts/install
+# Global CLI
+npm install -g @event4u/agent-config@latest
+agent-config --help
 ```
 
 The installer is idempotent — re-running it after an update refreshes

package/docs/migrations/commands-1.15.0.md

@@ -15,9 +15,9 @@ invocation and are removed in `1.16.0`.
 | Old command | New invocation | Removed in |
 |---|---|---|
 | `/fix-ci` | `/fix ci` | 1.16.0 |
-| `/fix-pr-comments` | `/fix pr` | 1.16.0 |
-| `/fix-pr-bot-comments` | `/fix pr-bots` | 1.16.0 |
-| `/fix-pr-developer-comments` | `/fix pr-developers` | 1.16.0 |
+| `/fix-pr-comments` | `/fix pr-comments` | 1.16.0 |
+| `/fix-pr-bot-comments` | `/fix pr-bot-comments` | 1.16.0 |
+| `/fix-pr-developer-comments` | `/fix pr-developer-comments` | 1.16.0 |
 | `/fix-portability` | `/fix portability` | 1.16.0 |
 | `/fix-references` | `/fix refs` | 1.16.0 |
 | `/fix-seeder` | `/fix seeder` | 1.16.0 |

package/docs/setup/per-ide/claude-desktop.md

@@ -3,10 +3,14 @@
 The fastest path to running our skills, rules, and (optionally) the MCP
 server inside Claude Desktop. macOS / Windows / Linux. ~5 minutes.
 
-> **TL;DR** — run `npx @event4u/agent-config init --tools=claude-code`
-> inside each project that should expose the skills/rules to Claude
-> Desktop. The package now ships as an npx-resolved runtime; the
-> retired `--global` symlink scheme has been removed.
+> **TL;DR** — Claude Desktop reads from `~/.claude/` (global only, no
+> project-local discovery on macOS). Run `npx @event4u/agent-config
+> global --tools=claude-desktop` once per user, or
+> `npx @event4u/agent-config init --tools=claude-code` per project
+> (Claude Code's project install also covers Desktop on macOS via the
+> shared `~/.claude/` location seeded during `init`). The v1 npm /
+> composer install scheme is retired; the new global-first scheme is
+> ADR-007 and writes through `~/.config/agent-config/installed.lock`.
 
 ## Prerequisites
 

package/docs/skills-catalog.md

@@ -1,6 +1,6 @@
 # Skills Catalog
 
-All **153 skills** available in this package, in alphabetical order.
+All **174 skills** available in this package, in alphabetical order.
 Click a skill name to open its SKILL.md and read the full guidance.
 
 > **Regenerate:** `python3 scripts/generate_catalog.py`
@@ -8,6 +8,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 
 | Skill | What your agent learns |
 |---|---|
+| [`accessibility-auditor`](../.agent-src/skills/accessibility-auditor/SKILL.md) | Use when reviewing UI for accessibility — WCAG 2.2 AA, keyboard nav, focus, ARIA, contrast, screen-reader semantics — even on 'is this a11y-OK?' or 'mach das barrierefrei'. |
 | [`adr-create`](../.agent-src/skills/adr-create/SKILL.md) | Use when capturing an architectural decision — naming the file, picking the next ADR number, filling Status / Context / Decision / Consequences, and regenerating the index — even without saying 'ADR'. |
 | [`adversarial-review`](../.agent-src/skills/adversarial-review/SKILL.md) | ONLY when user explicitly requests adversarial review, devil's advocate analysis, stress-testing a plan, or 'poke holes in this' — NOT for regular code review or design feedback. |
 | [`agent-docs-writing`](../.agent-src/skills/agent-docs-writing/SKILL.md) | Use when reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md. Understands the full .augment/, agents/, and copilot-instructions structure. |
@@ -18,6 +19,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`api-design`](../.agent-src/skills/api-design/SKILL.md) | Use when designing APIs, planning endpoints, REST conventions, versioning, or deprecation — even when the user just says 'expose this as an endpoint' without naming API design. |
 | [`api-endpoint`](../.agent-src/skills/api-endpoint/SKILL.md) | Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs. |
 | [`api-testing`](../.agent-src/skills/api-testing/SKILL.md) | Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing. |
+| [`architecture-review-lens`](../.agent-src/skills/architecture-review-lens/SKILL.md) | Use when a diff may break system boundaries, dependency direction, or cross-service contracts — fifth judge dispatched by /review-changes alongside the four standard judges. |
 | [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
 | [`async-python-patterns`](../.agent-src/skills/async-python-patterns/SKILL.md) | Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized. |
 | [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
@@ -30,16 +32,19 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`code-review`](../.agent-src/skills/code-review/SKILL.md) | Use when the user says "review this", "check my code", or wants feedback on changes. Reviews for correctness, quality, security, and coding standards. |
 | [`command-routing`](../.agent-src/skills/command-routing/SKILL.md) | Use when the user invokes a slash command like /create-pr, /commit, /fix-ci, or pastes command file content — routes to the right command with context inference and GitHub API patterns. |
 | [`command-writing`](../.agent-src/skills/command-writing/SKILL.md) | Use when creating or editing a slash command in .agent-src.uncompressed/commands/ — frontmatter, numbered steps, safety gates — even when the user just says 'add a /command for X'. |
+| [`competitive-positioning`](../.agent-src/skills/competitive-positioning/SKILL.md) | Use when comparing this package to a peer / competitor — ours-vs-theirs verdict table, axis selection, adoption queue. Triggers on 'how do we compare to X', 'should we adopt their pattern'. |
 | [`composer-packages`](../.agent-src/skills/composer-packages/SKILL.md) | Use when building or maintaining a Composer library — versioning, Laravel integration, autoloading, publishing to private registries — even when the user says 'release a new version'. |
 | [`context-authoring`](../.agent-src/skills/context-authoring/SKILL.md) | Use when filling in knowledge-layer context files — auth-model, tenant-boundaries, data-sensitivity, deployment-order, observability — interactive walkthrough that turns templates into reviewer fuel. |
 | [`context-document`](../.agent-src/skills/context-document/SKILL.md) | Use when the user says "create context", "document this area", or wants a structured snapshot of a codebase area for agent orientation. |
 | [`conventional-commits-writing`](../.agent-src/skills/conventional-commits-writing/SKILL.md) | Use when writing commit messages or squash-merge titles — `feat:`, `fix:`, `chore:`, scopes, breaking changes — even when the user just says 'commit this' without naming Conventional Commits. |
 | [`copilot-agents-optimization`](../.agent-src/skills/copilot-agents-optimization/SKILL.md) | Use when optimizing AGENTS.md or copilot-instructions.md — deduplicates against .augment/ content, enforces line budgets, and focuses each file on its audience. |
 | [`copilot-config`](../.agent-src/skills/copilot-config/SKILL.md) | Use when configuring GitHub Copilot — copilot-instructions.md, PR review patterns, output optimization — even when the user just says 'tune Copilot' or 'why is Copilot commenting on X'. |
+| [`customer-research`](../.agent-src/skills/customer-research/SKILL.md) | Use when shaping a discovery slice — JTBD-framed interview guide, switch-event focus, verbatim quotes not summaries. Triggers on 'talk to users', 'why did they cancel', 'before we build X'. |
 | [`dashboard-design`](../.agent-src/skills/dashboard-design/SKILL.md) | Use when designing monitoring dashboards — visualization selection, layout principles, observability strategies (RED/USE/Golden Signals), and data storytelling. |
 | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
 | [`database`](../.agent-src/skills/database/SKILL.md) | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
 | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
+| [`decision-record`](../.agent-src/skills/decision-record/SKILL.md) | Use when locking a trade-off, structuring an ADR draft, or wiring supersession chains — frames options · trade-offs · consequences before the file is written by `adr-create`. |
 | [`deep-reading-analyst`](../.agent-src/skills/deep-reading-analyst/SKILL.md) | Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary. |
 | [`defense-in-depth`](../.agent-src/skills/defense-in-depth/SKILL.md) | Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one. |
 | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
@@ -47,6 +52,7 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`design-review`](../.agent-src/skills/design-review/SKILL.md) | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
 | [`devcontainer`](../.agent-src/skills/devcontainer/SKILL.md) | Use when configuring DevContainers or GitHub Codespaces — devcontainer.json, custom images, secrets, VS Code features — even when the user just says 'why does my Codespace not start'. |
 | [`developer-like-execution`](../.agent-src/skills/developer-like-execution/SKILL.md) | Use when implementing, debugging, refactoring, or reviewing code — enforces the think → analyze → verify → execute workflow — even when the user just says 'implement X' without naming it. |
+| [`discovery-interview`](../.agent-src/skills/discovery-interview/SKILL.md) | Use when running discovery interviews — question-bank build, bias audit, insight extraction. Triggers on 'audit my guide', 'extract insights from transcript', 'is my hypothesis falsifiable'. |
 | [`docker`](../.agent-src/skills/docker/SKILL.md) | Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'. |
 | [`dto-creator`](../.agent-src/skills/dto-creator/SKILL.md) | Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping. |
 | [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) | Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions. |
@@ -58,11 +64,13 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`file-editor`](../.agent-src/skills/file-editor/SKILL.md) | Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled. |
 | [`finishing-a-development-branch`](../.agent-src/skills/finishing-a-development-branch/SKILL.md) | Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'. |
 | [`flux`](../.agent-src/skills/flux/SKILL.md) | Use when the project uses `livewire/flux` — dispatched by `directives/ui/{apply,review,polish}.py`. Covers Flux components, slots, variants, and form primitives. |
+| [`form-handler`](../.agent-src/skills/form-handler/SKILL.md) | Use when designing or reviewing a form — validation timing, error display, submission lifecycle, optimistic UI, dirty/pristine state, idempotency — even on 'why does submit double-fire?'. |
 | [`funnel-analysis`](../.agent-src/skills/funnel-analysis/SKILL.md) | Use when diagnosing where a SaaS or product funnel leaks — visitor → signup → activation → paid → retained — channel-agnostic, conversion-rate-driven. |
 | [`git-workflow`](../.agent-src/skills/git-workflow/SKILL.md) | Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git. |
 | [`github-ci`](../.agent-src/skills/github-ci/SKILL.md) | Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'. |
 | [`grafana`](../.agent-src/skills/grafana/SKILL.md) | Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana. |
 | [`guideline-writing`](../.agent-src/skills/guideline-writing/SKILL.md) | Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'. |
+| [`incident-commander`](../.agent-src/skills/incident-commander/SKILL.md) | Use during or right after an incident — frames severity, sets comms cadence, drafts the post-mortem skeleton — even when the user just says 'production is down' or 'wir haben einen Vorfall'. |
 | [`jira-integration`](../.agent-src/skills/jira-integration/SKILL.md) | Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking. |
 | [`jobs-events`](../.agent-src/skills/jobs-events/SKILL.md) | Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling. |
 | [`judge-bug-hunter`](../.agent-src/skills/judge-bug-hunter/SKILL.md) | Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'. |
@@ -79,15 +87,19 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`laravel-reverb`](../.agent-src/skills/laravel-reverb/SKILL.md) | Use when configuring Laravel Reverb — the first-party WebSocket server with Pusher protocol compatibility, horizontal scaling, and Pulse monitoring. |
 | [`laravel-scheduling`](../.agent-src/skills/laravel-scheduling/SKILL.md) | Use when configuring Laravel task scheduling — cron expressions, frequency helpers, overlap prevention, maintenance mode, or output handling. |
 | [`laravel-validation`](../.agent-src/skills/laravel-validation/SKILL.md) | Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it. |
+| [`launch-readiness`](../.agent-src/skills/launch-readiness/SKILL.md) | Use before merging a release-shaped PR — pre-merge checklist, rollout plan, rollback criteria, ops handoff. Triggers on 'ready to ship', 'launch checklist', 'rollout plan for X'. |
 | [`learning-to-rule-or-skill`](../.agent-src/skills/learning-to-rule-or-skill/SKILL.md) | Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work. |
 | [`lint-skills`](../.agent-src/skills/lint-skills/SKILL.md) | Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata. |
 | [`livewire`](../.agent-src/skills/livewire/SKILL.md) | Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation. |
+| [`livewire-architect`](../.agent-src/skills/livewire-architect/SKILL.md) | Use when shaping a Livewire component before code — full-page vs partial, parent/child split, event flow, state-vs-props boundary, hydration cost — even on 'add this Livewire component'. |
 | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
 | [`markitdown`](../.agent-src/skills/markitdown/SKILL.md) | Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'. |
 | [`mcp`](../.agent-src/skills/mcp/SKILL.md) | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
 | [`mcp-builder`](../.agent-src/skills/mcp-builder/SKILL.md) | Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness. |
 | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |
+| [`memory-consolidation`](../.agent-src/skills/memory-consolidation/SKILL.md) | Use when consolidating session signals into curated memory — four-phase loop ORIENT → GATHER → CONSOLIDATE → PRUNE. Triggers on 'mine my sessions', 'consolidate memory', 'review intake signals'. |
 | [`merge-conflicts`](../.agent-src/skills/merge-conflicts/SKILL.md) | Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow. |
+| [`migration-architect`](../.agent-src/skills/migration-architect/SKILL.md) | Use when shaping a non-trivial migration — rollout phases, dual-write windows, cutover sequencing, deprecation cycles — hands off to `migration-creator` for DDL once locked. |
 | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
 | [`mobile-e2e-strategy`](../.agent-src/skills/mobile-e2e-strategy/SKILL.md) | Use when picking a mobile E2E framework — Detox / Appium / Maestro / XCUITest / Espresso — or planning iOS Simulator / Android Emulator coverage in CI for RN, Expo, or native apps. |
 | [`module-management`](../.agent-src/skills/module-management/SKILL.md) | Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions. |
@@ -102,7 +114,9 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`php-coder`](../.agent-src/skills/php-coder/SKILL.md) | Writes or edits PHP code — controllers, classes, type hints, SOLID refactors, modern idioms — even without naming PHP. NOT for writing tests (use pest-testing) or explaining PHP concepts. |
 | [`php-debugging`](../.agent-src/skills/php-debugging/SKILL.md) | Use when debugging PHP with Xdebug — breakpoints, step-through, dual-container setup, IDE configuration, header-based routing — even when the user just says 'why does this blow up on request X'. |
 | [`php-service`](../.agent-src/skills/php-service/SKILL.md) | Use when the user says 'create service', 'new service class', or needs a PHP service following SOLID principles with proper DI and repository usage. |
+| [`playwright-architect`](../.agent-src/skills/playwright-architect/SKILL.md) | Use when shaping a Playwright suite — locator strategy, Page Object boundaries, fixture composition, flake-prevention architecture, CI-vs-local split — even on 'design our E2E tests'. |
 | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
+| [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) | Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research. |
 | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
 | [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |
@@ -124,10 +138,12 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`receiving-code-review`](../.agent-src/skills/receiving-code-review/SKILL.md) | Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'. |
 | [`"refine-prompt"`](../.agent-src/skills/"refine-prompt"/SKILL.md) | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'. |
 | [`"refine-ticket"`](../.agent-src/skills/"refine-ticket"/SKILL.md) | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
+| [`release-comms`](../.agent-src/skills/release-comms/SKILL.md) | Use when turning a shipped changelog into a release narrative — value-not-feature framing, audience-segmented surfaces, one source of truth. Triggers on 'announce the release', 'write changelog post'. |
 | [`repomix-packer`](../.agent-src/skills/repomix-packer/SKILL.md) | Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI. |
 | [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
 | [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
 | [`rice-prioritization`](../.agent-src/skills/rice-prioritization/SKILL.md) | Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort. |
+| [`risk-officer`](../.agent-src/skills/risk-officer/SKILL.md) | Use when surfacing and prioritising risk before commit — blast-radius framing, mitigations, residual-risk verdict — even if the user just says 'what could go wrong here?'. |
 | [`roadmap-management`](../.agent-src/skills/roadmap-management/SKILL.md) | Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking. |
 | [`roadmap-writing`](../.agent-src/skills/roadmap-writing/SKILL.md) | Use when authoring or rewriting a roadmap in agents/roadmaps/ — phase prose, goal sentence, acceptance criteria, council notes — even when the user just says 'write a plan for X' or 'draft a roadmap'. |
 | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
@@ -143,8 +159,11 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
 | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
-| [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) | Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml. |
+| [`stakeholder-tradeoff`](../.agent-src/skills/stakeholder-tradeoff/SKILL.md) | Use when stakeholders pull a decision in different directions — frames each lens, builds a trade-off matrix, surfaces the cost of every choice — even if the user just says 'PO and ops disagree'. |
+| [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
 | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
+| [`tailwind-engineer`](../.agent-src/skills/tailwind-engineer/SKILL.md) | Use when writing or reviewing Tailwind CSS — utility-first, design-token discipline, no inline-style drift, responsive variants, dark mode — even on 'style this' or 'mach das hübsch'. |
+| [`tech-debt-tracker`](../.agent-src/skills/tech-debt-tracker/SKILL.md) | Use when surfacing tech debt as trackable items — interest-vs-principal framing, prioritisation by carrying cost, repayment plan — even if the user just says 'this codebase is a mess'. |
 | [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) | Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure. |
 | [`terraform`](../.agent-src/skills/terraform/SKILL.md) | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
 | [`terragrunt`](../.agent-src/skills/terragrunt/SKILL.md) | Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt. |
@@ -154,12 +173,14 @@ Click a skill name to open its SKILL.md and read the full guidance.
 | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
 | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) | Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action. |
 | [`traefik`](../.agent-src/skills/traefik/SKILL.md) | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
+| [`ui-component-architect`](../.agent-src/skills/ui-component-architect/SKILL.md) | Use when shaping a UI component tree — composition vs inheritance, slot patterns, prop API design, controlled vs uncontrolled, polymorphic — even on 'split this component'. |
 | [`unit-economics-modeling`](../.agent-src/skills/unit-economics-modeling/SKILL.md) | Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses. |
 | [`universal-project-analysis`](../.agent-src/skills/universal-project-analysis/SKILL.md) | ONLY when user explicitly requests: full project analysis, deep codebase audit, or comprehensive architecture review. Routes to core and framework-specific analysis skills. |
 | [`upstream-contribute`](../.agent-src/skills/upstream-contribute/SKILL.md) | Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package. |
 | [`using-git-worktrees`](../.agent-src/skills/using-git-worktrees/SKILL.md) | Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'. |
 | [`"validate-feature-fit"`](../.agent-src/skills/"validate-feature-fit"/SKILL.md) | Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit |
 | [`verify-completion-evidence`](../.agent-src/skills/verify-completion-evidence/SKILL.md) | Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs. |
+| [`voc-extract`](../.agent-src/skills/voc-extract/SKILL.md) | Use when extracting Voice-of-Customer themes from existing artefacts — GH issues, PR threads, Sentry patterns. Triggers on 'what are users saying', 'recurring complaints', 'top themes'. |
 | [`websocket`](../.agent-src/skills/websocket/SKILL.md) | Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'. |
 
 ---