@event4u/agent-config 9.8.0 → 9.10.0

package/docs/setup/per-ide/windsurf.md

@@ -1,109 +0,0 @@
-# Windsurf Setup
-
-Windsurf reads two rule formats:
-
-- **Wave-8 (`.windsurf/rules/`)** — per-rule `.md` files with
-  `trigger`, `description`, `globs` frontmatter. Preferred for
-  Windsurf 1.5+.
-- **Legacy (`.windsurfrules`)** — single-file aggregate at the repo
-  root. Older Windsurf builds and the Cascade chat fallback both still
-  read it.
-
-The package ships **both**.
-
-## Prerequisites
-
-- Windsurf 1.0+ (Codeium): <https://codeium.com/windsurf>.
-- Node.js ≥ 18.
-
-## Project install
-
-```bash
-npx @event4u/agent-config init --tools=windsurf
-```
-
-Populates:
-
-- `.windsurf/rules/*.md`        — modern Wave-8 per-rule files
-- `.windsurf/workflows/*.md`    — slash-command workflows
-- `.windsurfrules`              — legacy single-file aggregate
-- `.agent-settings.yml`         — per-project knobs
-
-Combine with other surfaces:
-
-```bash
-npx @event4u/agent-config init --tools=windsurf,claude-code,cursor
-```
-
-## Wave-8 frontmatter
-
-Each rule under `.windsurf/rules/` has the Windsurf-shaped header:
-
-```md
----
-trigger: always_on
-description: Scope control — no unsolicited architectural changes
-globs:
----
-
-# Scope Control
-...
-```
-
-- `trigger: always_on` ↔ source `type: "always"` (kernel rules).
-- `trigger: model_decision` ↔ Cascade decides per turn (auto rules).
-- `globs:` is intentionally empty in the package's projection — set
-  per-rule in your fork if you want path-scoped triggering.
-
-## Workflows
-
-`.windsurf/workflows/<slug>.md` mirrors `.claude/commands/`. Cluster
-commands flatten to `<cluster>-<name>.md`. Cascade lists all workflow
-files in its workflow palette.
-
-## Cascade integration
-
-Cascade (Windsurf's built-in agent) reads `.windsurf/rules/` and
-`.windsurf/workflows/` automatically. No separate registration step is
-needed once the files are on disk.
-
-When Cascade asks a clarifying question, the package's `user-interaction`
-rule (kernel, `always_on`) applies — Cascade will surface numbered
-options with a single recommendation.
-
-## Workspace vs global precedence
-
-| Layer | Path | Precedence |
-|---|---|---|
-| Workspace | `.windsurf/rules/` + `.windsurf/workflows/` | wins on conflicts |
-| Global | `~/.codeium/windsurf/global_workflows/` | falls back when workspace silent |
-
-Reuse the same `--tools=windsurf` flag for both — `init` writes
-workspace, `global` writes user-level.
-
-## Verification
-
-```bash
-ls .windsurf/rules/     | head -5      # *.md per-rule files
-ls .windsurf/workflows/ | head -5      # *.md workflow files
-test -f .windsurfrules                 # legacy aggregate exists
-```
-
-In Windsurf itself: open Cascade → Workflows panel — listed workflows
-should match `ls .windsurf/workflows/`.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Rules not picked up | Windsurf < 1.0 — upgrade or rely on `.windsurfrules`. |
-| Workflow not in Cascade panel | Reload window after `task generate-tools`. |
-| Global workflows missing | Check `~/.codeium/windsurf/global_workflows/` exists. |
-| Frontmatter parse error | Re-run `./scripts-run src/scripts/condense --generate-tools`. |
-
-## Cross-references
-
-- [`docs/installation.md`](../../installation.md) — install matrix index.
-- [`src/templates/windsurf-rule.md.j2`](../../../templates/windsurf-rule.md.j2)
-  — template used by the projection generator.
-- [`AGENTS.md`](../../../AGENTS.md) — package self-orientation.

package/docs/setup/per-ide/zed.md

@@ -1,73 +0,0 @@
-# Zed Setup
-
-Zed (<https://zed.dev>) reads `.rules` at the project root as
-system-level instructions. The bridge drops a marker under `.zed/`
-and documents the wiring; Zed itself does not auto-discover
-`.zed/agent-config.md`.
-
-## Prerequisites
-
-- Zed editor: <https://zed.dev/download>.
-- Node.js ≥ 18 for the install entrypoints.
-
-## Install
-
-Project scope (default):
-
-```bash
-npx @event4u/agent-config init --tools=zed
-```
-
-Global scope (cross-project, deploys the universal skill bundle to
-`~/.config/zed/`):
-
-```bash
-npx @event4u/agent-config init --tools=zed --global
-```
-
-Populates (project):
-
-- `.zed/agent-config.md` — informational marker
-- `AGENTS.md`            — canonical agent self-orientation
-- `.agent-settings.yml`  — per-project knobs
-
-## How to use
-
-- After install, append the following line to `.rules` at the
-  project root (create the file if missing):
-
-  ```
-  @.augment/AGENTS.md
-  ```
-
-  Zed reads `.rules` on session start. The `@`-prefix tells Zed to
-  inline the referenced file as part of the system prompt.
-- Zed's Assistant panel honors the inlined rules across all
-  conversation modes.
-- Slash commands and skills live under `.augment/commands/` and
-  `.augment/skills/`. Zed does not register them natively — invoke
-  them by name in chat (e.g. *"run the create-pr command"*).
-
-## Verification
-
-```bash
-test -f .zed/agent-config.md
-test -f AGENTS.md
-grep -q "@.augment/AGENTS.md" .rules
-```
-
-In Zed: open the Assistant panel and ask *"What is this repo?"* —
-the answer should cite the AGENTS.md emergency triage block.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| Assistant ignores rules | Confirm `.rules` exists at project root and contains `@.augment/AGENTS.md`. |
-| `.rules` not auto-loaded | Restart Zed; `.rules` is read on session start. |
-| Inlined skill missing | Replace `@.augment/AGENTS.md` with the specific skill path you need to inline. |
-
-## Cross-references
-
-- [`AGENTS.md`](../../../AGENTS.md) — canonical agent self-orientation.
-- [`docs/installation.md`](../../installation.md) — install matrix index.

package/docs/showcase.md

@@ -1,209 +0,0 @@
-# Showcase — see the package in action
-
-Five copy-paste prompts that demonstrate what `event4u/agent-config`
-actually changes about an agent's behavior. Each example pairs a
-**prompt** with the **expected behavior** and the **rule or skill
-file** the behavior is anchored in — so every claim here is traceable
-back to a file you can read.
-
-These are not transcripts. They describe what a compliant agent does
-(and refuses to do) when the package is installed. If your agent
-does something else, the rule is either not loaded or being violated
-— either is reproducible and fixable.
-
-> Not installed yet? → [Installation](installation.md) ·
-> Settings reference → [`.agent-settings.yml` template](../dist/agent-src/templates/agent-settings.md)
-
----
-
-## 1. Autonomy on vs. off — same prompt, two outcomes
-
-Prove that `personal.autonomy` actually suppresses trivial workflow
-questions.
-
-**Setup:** open `.agent-settings.yml`, set `personal.autonomy: on`
-(then later `off` for the second run).
-
-**Prompt** (run twice, once per setting):
-
-```text
-Roadmap "phase-1.md" hat 4 Steps. Arbeite Schritt für Schritt durch.
-```
-
-**Expected behavior — `autonomy: on`:**
-
-- Agent picks the next unchecked step itself, no "Step 2 or 3?"
-- Runs it, marks `[x]`, moves on.
-- Only stops on blocking decisions: scope expansion, security-sensitive
-  paths, ambiguous requirements (those still get asked, autonomy
-  doesn't override them).
-- Never asks about committing — see Example 2.
-
-**Expected behavior — `autonomy: off`:**
-
-- Agent confirms each step before executing.
-- Surfaces "Should I start Step 2 now?" and waits.
-
-**Anchored in:** [`dist/agent-src/rules/autonomous-execution.md`](../dist/agent-src/rules/autonomous-execution.md)
-(trivial vs. blocking decisions, opt-in detection).
-
----
-
-## 2. Explicit commit grant — never automatic, never asked
-
-Prove that committing is gated by **explicit instruction**, never
-inferred from "we reached a clean stopping point".
-
-**Setup:** any state with uncommitted changes; `personal.autonomy: on`.
-
-**Prompt A** (no commit grant):
-
-```text
-Implementiere Feature X und teste es.
-```
-
-**Expected behavior:**
-
-- Agent implements, runs tests, reports done.
-- Does **not** commit. Does **not** ask "soll ich committen?".
-
-**Prompt B** (explicit grant):
-
-```text
-Implementiere Feature X, teste es, und commit das Ergebnis.
-```
-
-**Expected behavior:**
-
-- Agent implements, tests, **then commits** in logical chunks
-  (Conventional Commits format, no confirmation per chunk).
-
-**Same pattern applies to push, merge, branch creation, PR ops, tags**
-— allowed on explicit instruction, never automatic, never asked. The
-agent doesn't volunteer "soll ich pushen?"; you say "push das" or
-nothing happens.
-
-**Anchored in:** [`dist/agent-src/rules/commit-policy.md`](../dist/agent-src/rules/commit-policy.md)
-(four exceptions, never-ask iron law) ·
-[`dist/agent-src/rules/scope-control.md`](../dist/agent-src/rules/scope-control.md)
-(git operations permission gate).
-
----
-
-## 3. Vague request — agent asks instead of guessing
-
-Prove that ambiguous requirements trigger a clarifying question with
-numbered options, not a guess.
-
-**Prompt:**
-
-```text
-Add caching to this.
-```
-
-**Expected behavior:**
-
-- Agent does **not** pick a cache driver, scope, or invalidation
-  strategy on its own.
-- Surfaces numbered options:
-
-  ```text
-  > 1. Redis — durchgehend, geteilt zwischen Workern
-  > 2. Array — Request-lokal, kein externes System
-  > 3. File — persistent ohne Redis-Dependency
-
-  **Empfehlung: 1 — Redis** — …
-  ```
-
-- Recommendation line is mandatory (single-source iron law: exactly
-  one numbered recommendation, no inline `(recommended)` tag).
-
-**Anchored in:** [`dist/agent-src/rules/ask-when-uncertain.md`](../dist/agent-src/rules/ask-when-uncertain.md)
-(vague-request trigger table) ·
-[`dist/agent-src/rules/user-interaction.md`](../dist/agent-src/rules/user-interaction.md)
-(numbered-options + recommendation iron law).
-
----
-
-## 4. "done" without verification — agent refuses
-
-Prove that completion claims need **fresh evidence in this message**,
-not "tests should pass".
-
-**Setup:** any code change pending in the working tree.
-
-**Prompt:**
-
-```text
-Bist du fertig? Dann sag es und wir mergen.
-```
-
-**Expected behavior:**
-
-- Agent does **not** say "done", "ready", or "should be fine".
-- Runs the targeted test command for the change in this turn.
-- Runs the quality pipeline (PHPStan / linter / type-checker — whatever
-  the project uses) in this turn.
-- Only after both produce green output does the agent claim
-  completion, and the claim cites the command output by reference.
-- If verification fails, the agent reports the failure verbatim and
-  does not mask it with "kleinere Issues, behebe ich gleich".
-
-**Bypass:** `break-glass: true` (production incident) narrows the
-gate to a targeted test + smoke check + explicit list of skipped
-validations — never skips it entirely.
-
-**Anchored in:** [`dist/agent-src/rules/verify-before-complete.md`](../dist/agent-src/rules/verify-before-complete.md)
-(iron law, claim → command mapping, break-glass reduction).
-
----
-
-## 5. `/work "baue X"` — refine loop instead of blind code
-
-Prove that free-form prompts go through a refinement step (acceptance
-criteria, assumptions, confidence band) before the engine plans.
-
-**Prompt:**
-
-```text
-/work "baue eine API die User-Daten exportiert"
-```
-
-**Expected behavior:**
-
-- Agent does **not** start writing routes, controllers, or migrations.
-- Reconstructs the prompt into:
-  - **Acceptance criteria** — what "done" looks like (e.g. "GET
-    /api/users/export returns CSV", "auth required", "rate-limited").
-  - **Assumptions** — what was inferred (format = CSV? scope = own
-    user only? all users for admins?).
-  - **Confidence band** — high / medium / low, with the gaps named.
-- On low confidence, agent **blocks** and asks before any
-  implementation.
-- Only on high (or user-confirmed medium) confidence does the engine
-  proceed to plan → implement → test → verify → report.
-
-**Anchored in:** [`dist/agent-src/commands/work.md`](../dist/agent-src/commands/work.md)
-(Option-A loop, confidence-band gate, no auto-git) ·
-[`dist/agent-src/skills/refine-prompt/SKILL.md`](../dist/agent-src/skills/refine-prompt/SKILL.md)
-(AC + assumption reconstruction).
-
----
-
-## More
-
-The five examples above cover the load-bearing iron laws. For the
-**cycle-by-cycle traces** of the engine commands (`/implement-ticket`,
-`/work`, the UI track, and the blocked path), see
-[`end-to-end-walkthroughs.md`](end-to-end-walkthroughs.md) — each
-walkthrough is anchored to a checked-in golden transcript.
-
-The full rule set lives in [`dist/agent-src/rules/`](../dist/agent-src/rules/)
-(browse the `description:` line in each file's frontmatter to see
-when it auto-triggers); the full skill catalog is in
-[`docs/skills-catalog.md`](skills-catalog.md).
-
-**Suggesting an example?** Open a PR adding a new section here. Same
-shape: setup → prompt → expected behavior → anchor file. Keep claims
-traceable; don't ship transcripts that drift the moment a rule
-changes.

package/docs/skill-duplication-findings.md

@@ -1,91 +0,0 @@
-# Skill-duplication findings — Phase 3 consolidation discovery
-
-Replaces the *assumption* that "227 skills is duplicative" with **evidence**, and
-defines the merge-gate. **No skill is merged here** — any actual merge is a
-separate roadmap (per `preservation-guard` + `minimal-safe-diff`). Scope +
-method settled by AI-council (claude-sonnet-4-5 + gpt-4o, 2026-06-09).
-
-## Headline
-
-A within-family description-similarity scan over all **227 skills** surfaces only
-**10 pairs ≥ 0.35** TF-IDF cosine (5 ≥ 0.45) — and **every one has a documented
-reason to stay distinct.** **Zero merge candidates survive scrutiny.** The
-duplication assumption is not supported by the evidence.
-
-## Method (reproducible)
-
-- **Input:** `docs/contracts/skill-family-map.yml` (the Phase-2 spine).
-  Schema-validated against `src/skills/` first — fail-fast on drift (227 == 227 ✓).
-- **Similarity:** manual **TF-IDF cosine** over each skill's frontmatter
-  `description:` (the trigger/capability surface), tokens = lowercased alphanum
-  ≥ 3 chars minus a small stop-list. Compared **within family only** (the spine's
-  `family`) — cross-family pairs are noise (different domains).
-- **Dormancy:** `git log --since='6 months ago' -- src/skills/<name>/`.
-- Re-run: the one-shot logic above (no committed generator yet; a follow-up may
-  wire it into CI).
-
-## Findings — within-family pairs ≥ 0.35 (all keep-distinct)
-
-| Score | Family | Pair | Why keep distinct |
-|---|---|---|---|
-| 0.64 | backend-data | `laravel` ↔ `symfony-workflow` | different frameworks; `laravel-routing` / `symfony-routing` rules exist precisely to disambiguate |
-| 0.61 | debugging-analysis | `project-analyzer` ↔ `universal-project-analysis` | layered — single-pass vs deep multi-pass audit (the former's description routes to the latter) |
-| 0.49 | product-discovery | `estimate-ticket` ↔ `refine-ticket` | distinct workflow steps (size vs rewrite/AC) |
-| 0.46 | review-judging | `judge-bug-hunter` ↔ `judge-code-quality` | distinct single-scope **lenses** — merging violates the [review-lens dispatch contract](contracts/review-lens-schema.md) |
-| 0.46 | frontend-design | `blade-ui` ↔ `livewire` | distinct Laravel view stacks |
-| 0.41 | backend-data | `project-analysis-laravel` ↔ `project-analysis-node-express` | different stacks (analysis carve-outs) |
-| 0.38 | agent-admin | `command-routing` ↔ `command-writing` | routing (dispatch) vs authoring |
-| 0.36 | agent-admin | `roadmap-management` ↔ `roadmap-writing` | managing/progress vs authoring |
-| 0.35 | review-judging | `judge-bug-hunter` ↔ `judge-test-coverage` | distinct single-scope lenses (dispatch contract) |
-| 0.35 | backend-data | `project-analysis-laravel` ↔ `project-analysis-symfony` | different frameworks |
-
-**Dormancy:** **0 / 227** skills are git-dormant — but a corpus-wide restructure +
-condensation touched every skill in the last 6 months, so the 6-month commit
-signal is **currently uninformative**. It becomes meaningful once the tree
-settles; re-run then.
-
-## Scoped human-audit surface
-
-The maintainer's audit set (per the roadmap) is bounded to: (a) skills in
-`archive/skipped/stubs` — **none exist** in `src/skills/`; and (b) the 10
-highest-similarity pairs above. Evidence-based disposition for all 10:
-**keep distinct**, reasons recorded above. The maintainer may override, but no
-pair presents a duplication case on the evidence.
-
-## Merge gate
-
-```
-A MERGE CANDIDATE IS PROPOSED ONLY IF IT IS GENUINELY DUPLICATIVE
-AND ROUTING STAYS STABLE (>=95% OF CORPUS PROMPTS ROUTE TO THE SAME
-SKILL OR A DOCUMENTED REPLACEMENT) AFTER CONSOLIDATION.
-```
-
-- `validation_method: live_telemetry_required` · **`status: deferred`**.
-- **The ≥95% routing criterion is ADVISORY, not an automated gate, in this phase.**
-  Live telemetry is not deployed and there is no skill-*selection* oracle
-  (`skill_trigger_eval.py` measures trigger *coverage*, not which skill wins a
-  multi-match; only 14/227 skills carry `triggers.json`). A synthetic harness is
-  a **hypothesis generator, not a validator** — gating a merge on it would be
-  theatre. The gate activates when live selection telemetry exists.
-
-## `candidate_for_merge` (the Phase-3 spine conclusion)
-
-**Empty.** No skill is flagged `candidate_for_merge` — the evidence disposition is
-keep-distinct for all 10 surfaced pairs. The `skill-family-map.yml` `candidate_*`
-fields therefore remain absent (a populated value would assert a conclusion the
-evidence does not support).
-
-## Limitations
-
-- **Description-similarity only.** The capability signal is the `description:`
-  field; trigger-data is too sparse (14/227 `triggers.json`) for the council's
-  intended description+trigger composite. A future pass with full trigger data
-  could refine the scores.
-- **No selection oracle / synthetic predictions** ≠ production routing.
-- **Dormancy uninformative now** (post-restructure timestamp reset).
-
-## See also
-
-- [`skill-family-map.yml`](contracts/skill-family-map.yml) · [`skills-taxonomy.md`](skills-taxonomy.md) — the inputs.
-- [`review-lens-schema.md`](contracts/review-lens-schema.md) — the dispatch contract that protects the lens pairs above.
-- [`governance.md`](governance.md) — lifecycle + single-source-of-truth rules.