@event4u/agent-config 4.9.0 → 5.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agent-src/commands/implement-ticket.md +5 -4
- package/.agent-src/contexts/execution/roadmap-process-loop.md +30 -4
- package/.agent-src/rules/language-and-tone.md +4 -10
- package/.agent-src/rules/linked-projects-onboarding-gate.md +82 -0
- package/.agent-src/rules/roadmap-progress-sync.md +39 -5
- package/.agent-src/scripts/update_roadmap_progress.py +63 -7
- package/.agent-src/skills/command-routing/SKILL.md +5 -4
- package/.agent-src/skills/roadmap-management/SKILL.md +121 -21
- package/.agent-src/skills/roadmap-writing/SKILL.md +63 -0
- package/.agent-src/templates/agent-settings.md +16 -0
- package/.agent-src/templates/roadmaps.md +22 -1
- package/.agent-src/templates/scripts/work_engine/_lib/agent_settings.py +20 -3
- package/.claude-plugin/marketplace.json +1 -1
- package/CHANGELOG.md +106 -0
- package/CONTRIBUTING.md +19 -0
- package/README.md +12 -1
- package/dist/cli/registry.js +0 -2
- package/dist/cli/registry.js.map +1 -1
- package/dist/discovery/deprecation-report.md +1 -1
- package/dist/discovery/discovery-manifest.json +36 -14
- package/dist/discovery/discovery-manifest.json.sha256 +1 -1
- package/dist/discovery/discovery-manifest.summary.md +3 -3
- package/dist/discovery/orphan-report.md +1 -1
- package/dist/discovery/packs.json +6 -5
- package/dist/discovery/trust-report.md +3 -3
- package/dist/discovery/workspaces.json +5 -4
- package/dist/mcp/registry-manifest.json +3 -3
- package/dist/router.json +1 -1671
- package/docs/architecture.md +1 -1
- package/docs/benchmark.md +20 -8
- package/docs/benchmarks.md +11 -0
- package/docs/catalog.md +3 -2
- package/docs/contracts/benchmark-corpus-spec.md +31 -3
- package/docs/contracts/command-surface-tiers.md +1 -1
- package/docs/contracts/hook-architecture-v1.md +33 -0
- package/docs/contracts/migrate-command.md +197 -0
- package/docs/contracts/settings-api.md +2 -1
- package/docs/contracts/value-dashboard-spec.md +374 -0
- package/docs/contracts/value-report-schema.md +150 -0
- package/docs/decisions/ADR-031-validation-severity-tiers-and-projection-roundtrip.md +97 -0
- package/docs/decisions/ADR-032-linked-projects-scope.md +118 -0
- package/docs/decisions/INDEX.md +2 -0
- package/docs/getting-started.md +1 -1
- package/docs/guidelines/agent-infra/installed-tools-manifest.md +6 -3
- package/docs/guidelines/agent-infra/language-and-tone-examples.md +35 -0
- package/docs/guides/cross-repo-linked-projects.md +86 -0
- package/docs/migration/v1-to-v2.md +40 -27
- package/docs/value.md +84 -0
- package/package.json +8 -8
- package/scripts/__pycache__/validate_frontmatter.cpython-312.pyc +0 -0
- package/scripts/_cli/cmd_migrate.py +264 -102
- package/scripts/_cli/cmd_settings_migrate.py +2 -1
- package/scripts/_dispatch.bash +147 -49
- package/scripts/_lib/__pycache__/__init__.cpython-312.pyc +0 -0
- package/scripts/_lib/__pycache__/agent_src.cpython-312.pyc +0 -0
- package/scripts/_lib/agent_settings.py +20 -3
- package/scripts/_lib/install_regenerator.py +129 -0
- package/scripts/_lib/linked_projects.py +238 -0
- package/scripts/_lib/value_ladder.py +599 -0
- package/scripts/_lib/value_report.py +441 -0
- package/scripts/bench_rtk_savings.py +320 -0
- package/scripts/check_no_local_settings_committed.py +51 -0
- package/scripts/compile_router.py +19 -5
- package/scripts/expected_perms.json +1 -1
- package/scripts/first_run_gate_hook.py +178 -0
- package/scripts/hook_manifest.yaml +16 -7
- package/scripts/hooks/dispatch_hook.py +27 -0
- package/scripts/hooks/dispatch_issues.py +136 -0
- package/scripts/hooks_doctor.py +40 -1
- package/scripts/install.py +25 -21
- package/scripts/lint_agents_layout.py +5 -4
- package/scripts/lint_bench_corpus.py +86 -4
- package/scripts/lint_global_paths.py +4 -3
- package/scripts/lint_marketplace_install_completeness.py +188 -0
- package/scripts/lint_value_dashboard.py +218 -0
- package/scripts/render_benchmark_md.py +6 -2
- package/scripts/render_value_md.py +355 -0
- package/scripts/repro/repro_marketplace_install_gap.sh +161 -0
- package/scripts/roadmap_progress_hook.py +23 -0
- package/scripts/router_telemetry.py +470 -0
- package/scripts/validate_frontmatter.py +23 -9
- package/scripts/_cli/cmd_migrate_to_global.py +0 -415
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
---
|
|
2
|
+
adr: 032
|
|
3
|
+
status: accepted
|
|
4
|
+
date: 2026-05-29
|
|
5
|
+
decision: linked-projects-scope-go-option-a
|
|
6
|
+
supersedes: —
|
|
7
|
+
superseded_by: —
|
|
8
|
+
phase: v3.x · multi-project-scope evaluation
|
|
9
|
+
type: structural
|
|
10
|
+
review_date: 2027-05-29
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# ADR-032 — Linked-projects scope: GO on opt-in auto-detection (Option A, passive awareness)
|
|
14
|
+
|
|
15
|
+
## Status
|
|
16
|
+
|
|
17
|
+
**Accepted** · 2026-05-29. Approves an opt-in auto-detection feature for
|
|
18
|
+
IDE-attached sibling repositories, scoped to **passive awareness** (Option A).
|
|
19
|
+
A same-day earlier draft recorded NO-GO; that verdict was reversed after the
|
|
20
|
+
proactivity-gap argument (below). Time-boxed: review on **2027-05-29** or
|
|
21
|
+
earlier if a kill-switch trigger fires.
|
|
22
|
+
|
|
23
|
+
Not to be confused with [`ADR-029`](ADR-029-multi-workspace-deferred.md): that
|
|
24
|
+
defers a restructure of the **package's own root layout**. This ADR is about
|
|
25
|
+
the **agent's working scope over a sibling project repository**.
|
|
26
|
+
|
|
27
|
+
## Context
|
|
28
|
+
|
|
29
|
+
Developers routinely check out sibling repos that change together (e.g.
|
|
30
|
+
`galawork-api` + `galawork-web`) and attach them in the IDE. Detection is
|
|
31
|
+
deterministic from on-disk config (`.idea/modules.xml` + `vcs.xml`,
|
|
32
|
+
`*.code-workspace`).
|
|
33
|
+
|
|
34
|
+
A Phase-0 spike found Claude Code can already read/write a sibling outside its
|
|
35
|
+
working directory **unconditionally** — no rule needed. An initial reading
|
|
36
|
+
concluded the feature was therefore only an "awareness signal" a doc could
|
|
37
|
+
deliver, and drafted NO-GO.
|
|
38
|
+
|
|
39
|
+
## The reversal — proactivity gap
|
|
40
|
+
|
|
41
|
+
That NO-GO mis-framed the value. The point is **not** capability (the agent can
|
|
42
|
+
write everywhere); it is **proactivity**: the agent does **not** consider a
|
|
43
|
+
sibling unless explicitly told, so cross-repo dependencies — an API change that
|
|
44
|
+
breaks the frontend, a shared type that drifts — are missed by default. A
|
|
45
|
+
manual doc/snippet presupposes the very awareness the target user lacks: the
|
|
46
|
+
developer who needs this most is exactly the one who won't think to write the
|
|
47
|
+
note. **Auto-detection is zero-knowledge** — it reads the relationship the
|
|
48
|
+
developer already encoded by attaching the repo in their IDE.
|
|
49
|
+
|
|
50
|
+
AI Council (anthropic/claude-sonnet-4-5 + openai/gpt-4o, 3 rounds + Karpathy
|
|
51
|
+
peer-review, 2026-05-29) flipped to **GO** on this reasoning.
|
|
52
|
+
|
|
53
|
+
## Decision — GO, scoped to Option A (passive awareness)
|
|
54
|
+
|
|
55
|
+
Build an **opt-in** auto-detection feature:
|
|
56
|
+
|
|
57
|
+
1. **Detect** IDE-attached siblings from on-disk config (config-driven only;
|
|
58
|
+
never arbitrary adjacent directories).
|
|
59
|
+
2. **Opt-in once** per sibling; persist the choice **local-only** in
|
|
60
|
+
`.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — sibling paths differ
|
|
61
|
+
per developer and must never be committed).
|
|
62
|
+
3. **Behavioral directive** for in-scope siblings: proactively check cross-repo
|
|
63
|
+
impact on relevant changes (API contract, shared types) and **warn**.
|
|
64
|
+
**Do NOT bulk-include** the sibling's files (interpretation C — token
|
|
65
|
+
blowup — stays **out of scope**). Out-of-root writes still pass the host
|
|
66
|
+
agent's own permission gate.
|
|
67
|
+
|
|
68
|
+
### A/B/C scoping
|
|
69
|
+
|
|
70
|
+
- **A — passive awareness (CHOSEN):** know + warn, no bulk inclusion. Cheap, low risk.
|
|
71
|
+
- **B — proactive dependency scanning:** auto-scan on every change. Deferred (needs heuristics).
|
|
72
|
+
- **C — implicit inclusion of all sibling files:** **rejected** — token blowup, context pollution.
|
|
73
|
+
|
|
74
|
+
### Fork resolutions
|
|
75
|
+
|
|
76
|
+
- **Fork A** — `.agent-settings.local.yml` (in agents/settings/), deepest cascade layer reusing `_deep_merge` (not a bespoke override).
|
|
77
|
+
- **Fork B** — key `linked_projects` (avoids ADR-007 "scope"/"workspace", ADR-029 "multi-workspace").
|
|
78
|
+
- **Fork C** — cross-cwd writes documented, never auto-configured; host permission gate applies.
|
|
79
|
+
|
|
80
|
+
## Consequences
|
|
81
|
+
|
|
82
|
+
- New: detector (`scripts/_lib/linked_projects.py`), the
|
|
83
|
+
`.agent-settings.local.yml` (in agents/settings/) cascade layer, a committed-local lint, and the
|
|
84
|
+
`linked-projects-onboarding-gate` rule (tier-2b, **experimental**, **removable**).
|
|
85
|
+
- The intra-repo module system (`enumerate_modules()`) is untouched.
|
|
86
|
+
- Size never excludes a sibling — a real frontend (galawork-web ≈ 38k files)
|
|
87
|
+
must surface; it is flagged `large` (awareness only). The council's literal
|
|
88
|
+
"skip >20k files" guardrail was corrected: it conflated Option C's
|
|
89
|
+
file-inclusion cost with Option A, under which repo size is cost-irrelevant.
|
|
90
|
+
- Per install decision **D2**, the installer does not touch the consumer
|
|
91
|
+
`.gitignore`; consumers gitignore `.agent-settings.local.yml` (in agents/settings/) themselves
|
|
92
|
+
(documented in the guide).
|
|
93
|
+
|
|
94
|
+
## Kill-switch
|
|
95
|
+
|
|
96
|
+
Experimental + removable by construction. If opt-in is consistently declined or
|
|
97
|
+
siblings are never cited in practice, remove the rule. Signal stays local — no
|
|
98
|
+
telemetry.
|
|
99
|
+
|
|
100
|
+
## Open follow-ups
|
|
101
|
+
|
|
102
|
+
- **Consumer detector reachability:** the detector lives in `scripts/_lib/`;
|
|
103
|
+
exposing it as an `agent-config` CLI subcommand for consumer installs is a
|
|
104
|
+
follow-up. Import-reachable in this repo / co-located maintainer setups today.
|
|
105
|
+
- **Multi-agent verification:** only Claude Code was empirically validated.
|
|
106
|
+
Cursor / Augment / Copilot are unverified — the guide's manual snippet covers
|
|
107
|
+
them until an interactive per-IDE test is run.
|
|
108
|
+
|
|
109
|
+
## Alternatives considered
|
|
110
|
+
|
|
111
|
+
- **NO-GO + docs only** — rejected: a manual note fails the target user who lacks the awareness to write it.
|
|
112
|
+
- **Build Option C** — rejected: token blowup.
|
|
113
|
+
|
|
114
|
+
## References
|
|
115
|
+
|
|
116
|
+
- [`docs/guides/cross-repo-linked-projects.md`](../guides/cross-repo-linked-projects.md)
|
|
117
|
+
- [`ADR-007`](ADR-007-agent-discovery-scopes.md) — owns "scope"/"workspace".
|
|
118
|
+
- [`ADR-029`](ADR-029-multi-workspace-deferred.md) — unrelated package-root multi-workspace defer.
|
package/docs/decisions/INDEX.md
CHANGED
|
@@ -34,6 +34,8 @@ _Auto-generated by `scripts/adr/regenerate_index.py`. Do not edit._
|
|
|
34
34
|
| [ADR-028](ADR-028-root-layout.md) | Root Layout | accepted | 2026-05-25 | — |
|
|
35
35
|
| [ADR-029](ADR-029-multi-workspace-deferred.md) | Multi Workspace Deferred | accepted | 2026-05-25 | — |
|
|
36
36
|
| [ADR-030](ADR-030-claude-code-command-projection.md) | Claude Code Command Projection | accepted | 2026-05-28 | — |
|
|
37
|
+
| [ADR-031](ADR-031-validation-severity-tiers-and-projection-roundtrip.md) | Validation Severity Tiers And Projection Roundtrip | accepted | 2026-05-29 | — |
|
|
38
|
+
| [ADR-032](ADR-032-linked-projects-scope.md) | Linked Projects Scope Go Option A | accepted | 2026-05-29 | — |
|
|
37
39
|
|
|
38
40
|
## Unnumbered (legacy)
|
|
39
41
|
|
package/docs/getting-started.md
CHANGED
|
@@ -106,7 +106,7 @@ Your agent is now:
|
|
|
106
106
|
- **Respecting your codebase** — no conflicting patterns
|
|
107
107
|
- **Following standards** — consistent code quality
|
|
108
108
|
|
|
109
|
-
This is enforced automatically by
|
|
109
|
+
This is enforced automatically by 78 rules. No configuration needed.
|
|
110
110
|
|
|
111
111
|
---
|
|
112
112
|
|
|
@@ -89,9 +89,12 @@ intentionally pin an older version of the manifest.
|
|
|
89
89
|
Under [ADR-020](../../decisions/ADR-020-global-only-consumer-scope.md)
|
|
90
90
|
global is the only consumer scope. Consumers carrying a pre-2.5
|
|
91
91
|
project-scope payload move to global with the one-shot
|
|
92
|
-
`npx @event4u/agent-config migrate
|
|
93
|
-
|
|
94
|
-
the
|
|
92
|
+
`npx @event4u/agent-config migrate` subcommand — it removes the
|
|
93
|
+
legacy project artefacts in one opinionated pass (deletion-over-
|
|
94
|
+
migration policy); the wizard recreates fresh global config on the
|
|
95
|
+
next `agent-config setup`. See
|
|
96
|
+
[docs/contracts/migrate-command.md](../../contracts/migrate-command.md)
|
|
97
|
+
for the full action matrix.
|
|
95
98
|
|
|
96
99
|
For maintainers running `AGENT_CONFIG_DEV_MODE=1`, project-scope
|
|
97
100
|
re-installs remain available; the installer still detects scope
|
|
@@ -77,3 +77,38 @@ in an English `.md` file. Body text, example sentences, prompt templates,
|
|
|
77
77
|
agent-rendered strings, and failure modes must be English. Reference
|
|
78
78
|
established phrases abstractly later (e.g. "a standing autonomy directive")
|
|
79
79
|
and link back to the anchor block.
|
|
80
|
+
|
|
81
|
+
## Pre-send gate — filler-phrase blocklist
|
|
82
|
+
|
|
83
|
+
The pre-send confirm step (Step 4 of the rule's gate) checks for
|
|
84
|
+
language-of-target-mismatched opening phrases. The blocklist:
|
|
85
|
+
|
|
86
|
+
- **English filler that must NOT open a German reply:** `Let me`,
|
|
87
|
+
`Now`, `Found`, `Confirmed`, `OK`, `Alright`, `Here's`, `So`.
|
|
88
|
+
- **German filler that must NOT open an English reply:** `Lass mich`,
|
|
89
|
+
`Jetzt`, `Gefunden`, `Bestätigt`.
|
|
90
|
+
|
|
91
|
+
If the first sentence starts with one of these in the wrong language,
|
|
92
|
+
rewrite the whole reply.
|
|
93
|
+
|
|
94
|
+
## CLI / icon spacing rules
|
|
95
|
+
|
|
96
|
+
- Two spaces after `❌`, `✅`, `⚠️` in CLI output.
|
|
97
|
+
- One space for other icons.
|
|
98
|
+
- One blank line max; no double / triple blanks.
|
|
99
|
+
- File ends with exactly one newline.
|
|
100
|
+
|
|
101
|
+
## `.md` files — pre-save detection heuristic
|
|
102
|
+
|
|
103
|
+
Before saving any `.md` under `.augment/`, `.agent-src/`,
|
|
104
|
+
`.agent-src.uncondensed/`, or `agents/`, scan the body for:
|
|
105
|
+
|
|
106
|
+
- Umlauts (`ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`) **outside** fenced code,
|
|
107
|
+
paths, or `DE: … · EN: …` anchor blocks.
|
|
108
|
+
- German function words: `für`, `nicht`, `dass`, `wenn`, `sollte`,
|
|
109
|
+
`werden`, `arbeite`, `selbstständig`, `jetzt`, `einfach`, `weiter`,
|
|
110
|
+
`lösche`, `frag`, `schreib`, `mach`.
|
|
111
|
+
- Non-English quoted phrases in body text.
|
|
112
|
+
|
|
113
|
+
Any hit → translate to English, OR move to a `DE: … · EN: …` anchor
|
|
114
|
+
block (the only allowed German location).
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
# Working across linked sibling projects
|
|
2
|
+
|
|
3
|
+
When two repositories change together — an API and its frontend, a service and
|
|
4
|
+
a shared library — a change in one can silently break the other. The agent can
|
|
5
|
+
already read and write a sibling repo, but it won't **proactively consider** one
|
|
6
|
+
unless it knows the sibling is relevant. This feature closes that gap: it
|
|
7
|
+
detects the sibling your IDE already attached and, after a one-time opt-in,
|
|
8
|
+
makes the agent flag cross-repo impact by default.
|
|
9
|
+
|
|
10
|
+
> **Scope — passive awareness (Option A).** The agent gains *awareness*: it
|
|
11
|
+
> warns about cross-repo impact on relevant changes and can read/edit the
|
|
12
|
+
> sibling on demand. It does **not** bulk-load the sibling's files into context
|
|
13
|
+
> (that would blow up token cost). See
|
|
14
|
+
> [ADR-032](../decisions/ADR-032-linked-projects-scope.md). Unrelated to
|
|
15
|
+
> [ADR-029](../decisions/ADR-029-multi-workspace-deferred.md) (package root
|
|
16
|
+
> layout).
|
|
17
|
+
|
|
18
|
+
## Auto-detection (Claude Code — verified)
|
|
19
|
+
|
|
20
|
+
If you attach a sibling repo in your IDE, the agent detects it from on-disk
|
|
21
|
+
config and prompts **once** to opt it in:
|
|
22
|
+
|
|
23
|
+
- **PhpStorm / IntelliJ** — a sibling attached via `.idea/modules.xml` /
|
|
24
|
+
`.idea/vcs.xml` (e.g. `../galawork-web`).
|
|
25
|
+
- **VS Code** — folders in a `*.code-workspace`.
|
|
26
|
+
|
|
27
|
+
On the first turn (and on a new attachment) the agent asks per detected sibling:
|
|
28
|
+
include / decline / always / never-ask. Your choice is stored **local-only** in
|
|
29
|
+
`.agent-settings.local.yml` (in agents/settings/) (gitignored, per-machine — see below). A declined
|
|
30
|
+
sibling is never prompted again.
|
|
31
|
+
|
|
32
|
+
Once a sibling is in scope, the agent proactively checks it for impact when a
|
|
33
|
+
change here may affect it (API contract, shared types) and warns you — without
|
|
34
|
+
loading its files wholesale. Large siblings (a real frontend easily exceeds
|
|
35
|
+
20 000 files) are flagged `large` and surfaced as awareness only, never skipped.
|
|
36
|
+
|
|
37
|
+
## Manual setup (other agents / any editor)
|
|
38
|
+
|
|
39
|
+
Auto-detection is verified for Claude Code only. For Cursor, Augment, Copilot,
|
|
40
|
+
or any editor without IDE attachment, add the sibling by hand to
|
|
41
|
+
`.agent-settings.local.yml` (in agents/settings/):
|
|
42
|
+
|
|
43
|
+
~~~yaml
|
|
44
|
+
linked_projects:
|
|
45
|
+
- path: /abs/path/to/web # or a path relative to the project
|
|
46
|
+
include: true
|
|
47
|
+
~~~
|
|
48
|
+
|
|
49
|
+
Or, if your agent reads a rules file, drop a short note there:
|
|
50
|
+
|
|
51
|
+
~~~markdown
|
|
52
|
+
## Linked sibling project: ../web
|
|
53
|
+
|
|
54
|
+
`../web` changes alongside this repo. When an API/contract or shared-type
|
|
55
|
+
change here may affect it, check `../web` for impact and warn. Don't load its
|
|
56
|
+
files wholesale; access specific files on demand.
|
|
57
|
+
~~~
|
|
58
|
+
|
|
59
|
+
## Keep it local, never committed
|
|
60
|
+
|
|
61
|
+
`.agent-settings.local.yml` (in agents/settings/) is **gitignored on purpose** — sibling paths are
|
|
62
|
+
per-developer and per-machine. The installer does **not** touch your
|
|
63
|
+
`.gitignore` (decision D2 — you own your ignore file), so if your project does
|
|
64
|
+
not already ignore it, add:
|
|
65
|
+
|
|
66
|
+
~~~gitignore
|
|
67
|
+
.agent-settings.local.yml
|
|
68
|
+
~~~
|
|
69
|
+
|
|
70
|
+
## Validate it works
|
|
71
|
+
|
|
72
|
+
Ask the agent:
|
|
73
|
+
|
|
74
|
+
> Read `package.json` (or `composer.json`) from the linked sibling and tell me the project name.
|
|
75
|
+
|
|
76
|
+
If it reports the name, cross-repo access works. An out-of-root edit will prompt
|
|
77
|
+
for confirmation, then succeed — that is expected (the agent's permission gate
|
|
78
|
+
still applies).
|
|
79
|
+
|
|
80
|
+
## Tell us what works
|
|
81
|
+
|
|
82
|
+
Auto-detection is verified for Claude Code only. If you use Cursor, Augment, or
|
|
83
|
+
Copilot, please report whether the rule note alone worked, you needed to add the
|
|
84
|
+
folder to the IDE workspace, or neither — that evidence is the trigger to extend
|
|
85
|
+
verified auto-detection to your agent. See
|
|
86
|
+
[ADR-032](../decisions/ADR-032-linked-projects-scope.md).
|
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
# Migration — v1 → v2 (npx-only runtime)
|
|
2
2
|
|
|
3
|
-
> **Status:**
|
|
4
|
-
> is implemented in
|
|
5
|
-
>
|
|
6
|
-
>
|
|
7
|
-
>
|
|
3
|
+
> **Status:** active. The one-shot `npx @event4u/agent-config migrate`
|
|
4
|
+
> is implemented in `scripts/_cli/cmd_migrate.py`; its action matrix +
|
|
5
|
+
> exit-code contract live in
|
|
6
|
+
> [`docs/contracts/migrate-command.md`](../contracts/migrate-command.md).
|
|
7
|
+
> This document is the user-facing narrative; the contract is the
|
|
8
|
+
> normative reference.
|
|
8
9
|
|
|
9
10
|
## Why this change
|
|
10
11
|
|
|
@@ -56,32 +57,44 @@ The per-tool glue (`.claude/`, `.cursor/`, `.clinerules/`,
|
|
|
56
57
|
the source that writes them changed (from `vendor/` /
|
|
57
58
|
`node_modules/` scripts to the npx-resolved runtime).
|
|
58
59
|
|
|
59
|
-
## The `migrate` command
|
|
60
|
+
## The `migrate` command
|
|
60
61
|
|
|
61
62
|
```bash
|
|
62
|
-
npx @event4u/agent-config migrate #
|
|
63
|
-
npx @event4u/agent-config migrate --dry-run # plan only,
|
|
64
|
-
npx @event4u/agent-config migrate --yes # non-interactive
|
|
63
|
+
npx @event4u/agent-config migrate # apply, real changes
|
|
64
|
+
npx @event4u/agent-config migrate --dry-run # plan only, zero writes
|
|
65
65
|
```
|
|
66
66
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
`
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
67
|
+
One opinionated command, one flag. The full action matrix +
|
|
68
|
+
exit-code contract is documented in
|
|
69
|
+
[`docs/contracts/migrate-command.md`](../contracts/migrate-command.md);
|
|
70
|
+
the operations summary below is the narrative form.
|
|
71
|
+
|
|
72
|
+
Order of operations (fixed; foundation-first):
|
|
73
|
+
|
|
74
|
+
1. Detect every legacy signal in one pass: `composer.json` require
|
|
75
|
+
entry, `package.json` devDependency, managed symlinks pointing
|
|
76
|
+
into `vendor/` / `node_modules/`, v0
|
|
77
|
+
`.implement-ticket-state.json`, project-local `.agent-settings.yml`
|
|
78
|
+
/ `.agent-user.yml` (flat or under `settings/`), empty
|
|
79
|
+
`agent-config/` shell.
|
|
80
|
+
2. Under `--dry-run`, print the planned change set and stop with
|
|
81
|
+
exit 0.
|
|
82
|
+
3. Strip the package entries from `package.json` / `composer.json`
|
|
83
|
+
in-place; preserve sibling keys + formatting.
|
|
84
|
+
4. Purge legacy symlinks; preserve user-managed symlinks elsewhere
|
|
85
|
+
with a warning.
|
|
86
|
+
5. Migrate `.implement-ticket-state.json` → `.work-state.json`
|
|
87
|
+
(renames the v0 source to `.bak`).
|
|
88
|
+
6. **Hard-delete** legacy project-local config files. The wizard
|
|
89
|
+
(`agent-config setup`) recreates fresh global config on the next
|
|
90
|
+
run — deletion is the design, not a regression.
|
|
91
|
+
7. Remove the empty `agent-config/` shell directory if present.
|
|
92
|
+
8. Refresh the `.gitignore` agent-config managed block.
|
|
93
|
+
9. Print a summary listing every action taken.
|
|
94
|
+
|
|
95
|
+
Idempotency: re-running on a fully-migrated repo prints
|
|
96
|
+
*"already migrated — nothing to do"* and exits 0 without touching
|
|
97
|
+
the filesystem.
|
|
85
98
|
|
|
86
99
|
## Verification after migration
|
|
87
100
|
|
package/docs/value.md
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
# Value Dashboard — was kostet das Paket, was bringt es?
|
|
2
|
+
|
|
3
|
+
> Diese Seite beantwortet **eine** Frage in echten Zahlen: *Wie viel mehr Tokens kostet mich das Paket, und wie viel spart es danach wieder ein?* Generiert von `scripts/render_value_md.py` aus dem letzten `value-v1` Report; Quelle: `internal/bench/reports/value/latest.json`.
|
|
4
|
+
|
|
5
|
+
## Wie diese Seite zu lesen ist
|
|
6
|
+
|
|
7
|
+
**Panel A (Kostenleiter)** — von oben nach unten lesen. Jede Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro Request hinzufügt oder spart*, *was das in € auf 1,000 Requests kostet*, und *wo wir kumulativ stehen*. Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort.
|
|
8
|
+
|
|
9
|
+
**Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. *ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-Auswahl, Stopps bei riskanten Aktionen, weniger Rückfragen, mehr abgeschlossene Aufgaben.
|
|
10
|
+
|
|
11
|
+
**Confidence-Marker** an jeder Stufe: `✅ gemessen` = echter Wert aus einem Report im Repo · `⏳ pending` = noch nicht gemessen, Stufe trägt 0 zur Summe bei · `⚠️ vendor-claim` = Behauptung eines Herstellers, nicht selbst gemessen.
|
|
12
|
+
|
|
13
|
+
## Reference scale
|
|
14
|
+
|
|
15
|
+
- **1,000** Requests, durchschnittlich **8,000** Input-Tokens und **600** Output-Tokens pro Request
|
|
16
|
+
- Modell-Tier: `sonnet` · Preisstand `2026-05-14` (Quelle: `internal/bench/pricing.yaml`)
|
|
17
|
+
- Wer einen anderen Workload fährt, rechnet selbst nach — die Methodik ist offengelegt; nichts ist hardcodiert versteckt.
|
|
18
|
+
|
|
19
|
+
## Panel A — Kostenleiter (kumulativ, min → max)
|
|
20
|
+
|
|
21
|
+
Liest sich von oben nach unten. Positive Δ-Werte = das Paket *kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); negative Δ-Werte = das Paket *spart* Tokens.
|
|
22
|
+
|
|
23
|
+
| Stufe | Was sie tut | Δ Tokens | Δ € (1k Req) | Kumulativ | Quelle |
|
|
24
|
+
|---|---|---:|---:|---:|---|
|
|
25
|
+
| **Ohne Paket / Without package** | Baseline — der nackte Request ohne Paket-Regeln. | +0 | +0.00 € | +0.00% | `n/a` · ✅ gemessen |
|
|
26
|
+
| Mit Paket (Regeln laden) / With package (rule load) | Die immer-aktiven Regeln landen im Kontext jedes Requests. ⚠️ erst teurer | +8 895 | +24.55 € | +111.19% | `dist/router.json` · ✅ gemessen |
|
|
27
|
+
| | _Fußnote:_ Kernel = 10 rules (31570 chars) + charter (4010 chars); tokens ≈ chars / 4. | | | | |
|
|
28
|
+
| + condense (Regeln eindampfen) / + condense (rule shrink) | Build-Schritt schrumpft Regel-Dateien vor dem Ausliefern. | -186 | -0.51 € | +108.86% | `internal/bench/reports/telegraph-v2.json` · ✅ gemessen |
|
|
29
|
+
| | _Fußnote:_ Aggregate across non-Thin-Root categories; Thin-Root files (AGENTS.md variants) net negative (~−4%) and are excluded from the rung — surfaced separately. | | | | |
|
|
30
|
+
| + rtk (CLI-Output filtern) / + rtk (filter CLI output) | rtk schneidet verbose CLI-Ausgabe vor dem Modell-Input weg. | -593 | -1.64 € | +101.45% | `internal/bench/reports/rtk/latest.json` · ✅ gemessen |
|
|
31
|
+
| + terse (Antworten knapper) / + terse (shorter replies) | Telegraph-Stil zielt auf knappere Modell-Antworten. | +56 | +0.77 € | +102.15% | `internal/bench/reports/telegraph-v1.json` · ✅ gemessen |
|
|
32
|
+
| | _Fußnote:_ Honest: gemessener Median = -9.27% gegen 'sei knapp' — Telegraph liefert hier mehr Tokens, nicht weniger. Wir messen, wir verstecken nicht. | | | | |
|
|
33
|
+
|
|
34
|
+
**NETTO: Mehrkosten** ⚠️ — **+8 172 Tokens / Request**, **+22.55 €** auf 1,000 Requests, kumulativ **+102.15%** vs. Baseline.
|
|
35
|
+
|
|
36
|
+
## Panel B — Verhalten (mit vs. ohne)
|
|
37
|
+
|
|
38
|
+
Vier reale Vergleiche aus echten Bench-Runs. Hier liegt der Wert, den Tokens allein nicht messen: ob der Agent das richtige Skill wählt, bei riskanten Aktionen stoppt, weniger rückfragt und mehr Aufgaben abschließt.
|
|
39
|
+
|
|
40
|
+
| Metrik | Was es bedeutet | Mit Paket | Ohne Paket | Δ | Mode |
|
|
41
|
+
|---|---|---:|---:|---:|---|
|
|
42
|
+
| Right-skill selection / Richtige Skill-Wahl | Wie oft das passende Skill aktiviert wird (top-K Treffer). | 50.0% | 0.0% | 50.0% | ✅ live |
|
|
43
|
+
| Destructive-op stops / Stopps bei riskanten Aktionen | Wie oft der Agent vor destructive ops anhält / nachfragt (von 5). | — | — | — | ⚠️ dry-run |
|
|
44
|
+
| Ask-vs-act ratio / Fragen vs. Handeln | Verhältnis Rückfragen zu Aktionen — niedriger = entschlossener. | 0.000 | 0.000 | 0.000 | ✅ live |
|
|
45
|
+
| Task completion rate / Aufgaben fertig | Anteil der Aufgaben, die der Agent vollständig abschließt. | 84.6% | 7.7% | 76.9% | ✅ live |
|
|
46
|
+
|
|
47
|
+
## Glossar
|
|
48
|
+
|
|
49
|
+
Plain-language Definitionen für den nicht-Entwickler-Reader.
|
|
50
|
+
|
|
51
|
+
- **Token** — die Einheit, in der ein Sprachmodell abrechnet. Faustregel: ein Token ≈ 4 Zeichen deutsch/englischer Prosa. 1.000 Tokens ≈ 750 Wörter.
|
|
52
|
+
- **Input-Tokens** — alles, was das Modell pro Turn liest (System-Prompt, immer-aktive Regeln, deine Nachricht, frühere Konversation). Das Paket fügt hier Regeln hinzu — Installation kostet Input-Tokens.
|
|
53
|
+
- **Output-Tokens** — was das Modell zurückschreibt. Meist weniger als Input. Pro Token teurer als Input.
|
|
54
|
+
- **condense** — ein Build-Schritt, der die Regel-Dateien vor dem Ausliefern schrumpft (`.agent-src.uncondensed` → `.agent-src`). Spart Input-Tokens bei jedem Request.
|
|
55
|
+
- **rtk** — der *Rust Token Killer*, ein CLI-Wrapper, der verbose Output (`git status`, lint-Output, test-Runner) filtert, bevor das Modell ihn liest. Spart Input-Tokens auf Tool-Calls.
|
|
56
|
+
- **terse / telegraph** — ein Stil (kurze Phrasen, weggelassene Artikel), den der Agent für knappere Antworten nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.
|
|
57
|
+
- **Ohne Paket / Mit Paket** — *without the package* / *with the package* — die zwei Arme des A/B-Vergleichs.
|
|
58
|
+
- **€-per-1k-requests** — Token-Kosten auf der Referenz-Skala (1.000 Requests durchschnittlicher Größe, gepreist mit den aktuellen Sonnet-Raten aus `internal/bench/pricing.yaml`).
|
|
59
|
+
|
|
60
|
+
## Methodik & Quellen
|
|
61
|
+
|
|
62
|
+
Diese Seite ist eine **abgeleitete** Sicht — keine eigene Messung. Sie fasst drei bestehende Bench-Surfaces zusammen (siehe Spalte 'Quelle' in Panel A). Die maschinen-lesbaren Roh-Reports bleiben die Source-of-Truth:
|
|
63
|
+
|
|
64
|
+
- `internal/bench/reports/telegraph-v1.json` / `telegraph-v2.json` — Telegraph/Condense-Messungen.
|
|
65
|
+
|
|
66
|
+
- `agents/runtime/frugality/baseline.jsonl` — der Paket-Load (Metric A footprint).
|
|
67
|
+
|
|
68
|
+
- `internal/bench/reports/rtk/latest.json` — die rtk-Messung (neu, Phase 2).
|
|
69
|
+
|
|
70
|
+
- `internal/bench/reports/ab/*-ab-trackb-{with,without}.json` — A/B Track B (Verhalten).
|
|
71
|
+
|
|
72
|
+
- `internal/bench/reports/*-dev.json` — Dev-Korpus Selection-Accuracy.
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
**A/B-technischer Anhang:** [`docs/benchmark.md`](benchmark.md) trägt die Cache-Key-, Integrity- und Methodik-Details des A/B-Benches — wer den Variant-Axis-Beweis sehen will, liest dort weiter.
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
**Hinweise aus dem Report:**
|
|
79
|
+
|
|
80
|
+
- Token→€ conversion priced at sonnet rates from internal/bench/pricing.yaml (sourced_on=2026-05-14).
|
|
81
|
+
- Pending rungs contribute 0 to the cumulative until measured.
|
|
82
|
+
- Reference scale: 1000 requests × 8000 input / 600 output tokens per request.
|
|
83
|
+
|
|
84
|
+
_Last rendered: `2026-05-29T04:36:04+00:00`_
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@event4u/agent-config",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "5.1.0",
|
|
4
4
|
"description": "Universal AI Agent OS \u2014 audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"private": false,
|
|
@@ -93,15 +93,15 @@
|
|
|
93
93
|
"vitest": "^2.1.9"
|
|
94
94
|
},
|
|
95
95
|
"dependencies": {
|
|
96
|
-
"@fastify/static": "^9.1.
|
|
96
|
+
"@fastify/static": "^9.1.0",
|
|
97
97
|
"@preact/signals": "^2.9.0",
|
|
98
98
|
"commander": "^12.1.0",
|
|
99
|
-
"execa": "^9.
|
|
100
|
-
"fastify": "^5.8.
|
|
101
|
-
"js-yaml": "^4.1.
|
|
99
|
+
"execa": "^9.5.0",
|
|
100
|
+
"fastify": "^5.8.0",
|
|
101
|
+
"js-yaml": "^4.1.0",
|
|
102
102
|
"open": "^10.2.0",
|
|
103
|
-
"preact": "^10.29.
|
|
104
|
-
"zod": "^3.25.
|
|
105
|
-
"zod-to-json-schema": "^3.25.
|
|
103
|
+
"preact": "^10.29.0",
|
|
104
|
+
"zod": "^3.25.0",
|
|
105
|
+
"zod-to-json-schema": "^3.25.0"
|
|
106
106
|
}
|
|
107
107
|
}
|
|
Binary file
|