@event4u/agent-config 5.10.1 → 6.0.0

package/CONTRIBUTING.md

@@ -54,18 +54,29 @@ All checks must pass before a PR is merged:
 
 ## Source of truth
 
-- **Edit** `.agent-src.uncondensed/` — the authoring layer with verbose content.
-- **Do not edit** `.agent-src/` directly — it is the condensed output shipped
-  in the package, generated from the uncondensed layer by `task sync`.
-- **Do not edit** `.augment/` directly either — it is a local projection of
-  `.agent-src/` for Augment Code (gitignored), rebuilt by `task sync`.
-- **Do not edit** `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` —
-  they are generated projections for specific tools.
+`src/` is the single source of truth — the authoring layer you edit:
+`src/skills/`, `src/rules/`, `src/agent-src/` (profiles, user-types, commands,
+contexts, personas, packs), `src/domains/<pack>/`, `src/scripts/`.
+
+- **Edit** `src/` — verbose, authored content.
+- **Do not edit** `dist/agent-src/` directly — it is the **condensed output
+  shipped in the package**, generated from `src/` by `task sync`.
+- **Do not edit** `.augment/` directly either — it is a generated projection of
+  `dist/agent-src/` for Augment Code (gitignored in this repo; the installed
+  runtime tree in a consumer project — a deployment role, not source privilege).
+- **Do not edit** `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules`,
+  `GEMINI.md` — generated projections for specific tools.
+
+**The build chain:** `src/` → `task sync` condenses → `dist/agent-src/` (the
+shipped, published artefact) → projected → `.augment/` + the per-tool trees. No
+tool is privileged; every projection is read-only output. The condensed output
+lands in `dist/agent-src/` (and, in a consumer install, in that project's
+`.augment/`). Authoritative: the `source-of-truth` rule.
 
 Helper commands:
 
 ```bash
-task sync             # .agent-src.uncondensed/ → .agent-src/, then project → .augment/
+task sync             # src/ → dist/agent-src/, then project → .augment/
 task generate-tools   # Regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
 task test             # pytest tests/ + installer integration tests
 task lint-skills      # python3 scripts/skill_linter.py --all
@@ -84,17 +95,18 @@ task lint-skills      # python3 scripts/skill_linter.py --all
 
 ## Adding or editing skills, rules, and commands
 
-- Skills, rules, and commands live in `.agent-src.uncondensed/`.
+- Skills and rules live in `src/skills/` and `src/rules/`; commands in
+  `src/domains/<pack>/` and `src/agent-src/commands/`.
 - Each skill must pass `task lint-skills` — frontmatter, structure, size
   budgets, and self-containment are enforced by the linter.
 - Size budgets are enforced by the `size-enforcement` rule and the linter.
-  See [`size-enforcement`](.agent-src/rules/size-enforcement.md)
+  See [`size-enforcement`](dist/agent-src/rules/size-enforcement.md)
   for the current limits.
-- After editing content under `.agent-src.uncondensed/`, run `task sync` so
-  `.agent-src/`, `.augment/`, and the tool-specific projections stay in sync.
-- Skills must remain project-agnostic. Nothing in `.agent-src/` may reference a
+- After editing content under `src/`, run `task sync` so
+  `dist/agent-src/`, `.augment/`, and the tool-specific projections stay in sync.
+- Skills must remain project-agnostic. Nothing in `dist/agent-src/` may reference a
   specific consumer project, domain, or stack. The
-  [`augment-portability`](.agent-src/rules/augment-portability.md) rule and
+  [`augment-portability`](dist/agent-src/rules/augment-portability.md) rule and
   `scripts/check_portability.py` enforce this in CI.
 
 ## Agent-assisted contribution workflow
@@ -115,7 +127,7 @@ intent — *"a skill that validates JWT tokens"*, *"a rule banning
 silent fallbacks"* — and the agent:
 
 - picks the right artefact type (skill vs. rule vs. command vs. guideline);
-- places it in the correct directory under `.agent-src.uncondensed/`;
+- places it in the correct directory under `src/`;
 - writes frontmatter, trigger phrase (≤ 200 chars, multi-trigger coverage),
   required sections, and a size budget that fits the linter;
 - runs `task sync` so the condensed and projected copies stay aligned;

package/MIGRATION.md

@@ -0,0 +1,102 @@
+# Migrating to 6.0
+
+> Upgrading an existing install to the **6.0 experience-first** layout.
+> One command does the work: **`npx @event4u/agent-config migrate`**.
+> For the full breaking-change log see [`CHANGELOG.md`](CHANGELOG.md).
+
+6.0 is a structural release. Two things changed that a long-lived
+install can trip over:
+
+1. **npx-only runtime.** The package is consumed through its published
+   binary (`npx @event4u/agent-config …`), never by reaching into
+   `node_modules/@event4u/agent-config/{scripts,templates,config}/…`
+   directly. Those internal trees moved under `src/` in 6.0 — any path
+   you hardcoded into a script or CI step is gone. Call the binary
+   instead.
+2. **Profiles, packs, and verb-slug commands.** The surface is now a
+   focused per-profile command set (`agent-config setup` picks the
+   profile), capability **packs** are renamed to capability names, and
+   visible commands use `<pack>-<verb>` slugs (e.g. `commit` →
+   `git-commit`, `create-pr` → `git-pr-create`). Old invocations keep
+   routing through `replaces:` aliases until the alias window closes in
+   6.1 — so existing muscle memory and docs keep working through one
+   more minor.
+
+The `migrate` command performs the **install-side** cleanup
+(deletion-over-migration): it removes legacy package entries + symlinks
++ project-local config so the wizard can recreate fresh config. It does
+**not** rewrite your command invocations — the `replaces:` aliases do
+that at routing time.
+
+## Quick start
+
+```bash
+# 1. See whether you're on the old layout and what would change (no writes).
+npx @event4u/agent-config migrate --check        # exit 0 = clean, 2 = pending
+
+# 2. Preview the exact actions (no writes).
+npx @event4u/agent-config migrate --dry-run
+
+# 3. Apply.
+npx @event4u/agent-config migrate
+
+# 4. Recreate fresh project + global config.
+npx @event4u/agent-config setup
+```
+
+`--from 4` / `--from 5` optionally declares your source major (4.x =
+composer-era, 5.x = npx-era). Detection is signal-based, so the flag is
+advisory — it documents intent and warns on a mismatch; it never
+changes which actions run. Full behaviour:
+[`docs/contracts/migrate-command.md`](docs/contracts/migrate-command.md).
+
+## From 4.x → 6.0
+
+4.0 was the unified-wizard hard-cut: the Fastify wizard
+(`agent-config install` / `setup`) replaced the legacy Python / standalone
+installers. A 4.x consumer typically still carries one or more of:
+
+- a `event4u/agent-config` entry in `composer.json` (composer-era), or
+  an `@event4u/agent-config` entry in `package.json`;
+- managed symlinks (`.augment`, `.claude`, `.cursor`, `.clinerules`,
+  `.windsurfrules`) pointing into `vendor/` or `node_modules/`;
+- a project-local `.agent-settings.yml` / `.agent-user.yml` (flat or
+  under `settings/`);
+- a v0 work-engine state file (`.implement-ticket-state.json`).
+
+`migrate` strips the package entries, deletes the legacy symlinks,
+converts the v0 state file to `.work-state.json` (keeping a `.bak`),
+hard-deletes the project-local config, drops the empty `agent-config/`
+shell, and refreshes the managed `.gitignore` block. Then run
+`agent-config setup` — the wizard writes fresh config from your chosen
+profile. Rollback is git: the migration only deletes tracked /
+recreatable artefacts, so `git restore` / `git checkout` reverts it.
+
+## From 5.x → 6.0
+
+5.x removed `scripts/install.py` from the npx flow (the `curl | bash`
+fallback retired) and is otherwise npx-native, so a 5.x consumer is
+already close to the 6.0 shape. The two deltas:
+
+- **Internal paths moved under `src/`.** If any of your scripts or CI
+  steps reference `node_modules/@event4u/agent-config/scripts/…` (or
+  `templates/` / `config/`), repoint them to the published binary —
+  `npx @event4u/agent-config <command>` — rather than the moved
+  internal path. The package no longer publishes those trees at the
+  old top-level locations.
+- **Command renames.** Pack-rename + verb-slug invocations (above) take
+  effect; the `replaces:` aliases keep your old invocations routable
+  through 6.1, but update docs/scripts to the canonical slugs at your
+  convenience.
+
+`migrate --check` reports whether any legacy install signal remains;
+on a clean 5.x→6.0 consumer it exits 0 with
+`✅  on the 6.0 layout — no migration needed.`
+
+## What `migrate` does not touch
+
+- It never rewrites your command invocations (the `replaces:` alias map
+  handles old → new slugs at routing time).
+- It never lifts stale project YAML into global config — the wizard
+  recreates config fresh (deletion-over-migration). See
+  [`docs/contracts/migrate-command.md` § Excluded](docs/contracts/migrate-command.md).

package/README.md

@@ -2,7 +2,7 @@
 
 # Agent Config — Universal AI Agent OS
 
-[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config)
+[![Smoke](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke.yml) [![Public install smoke (3 OS × 2 Node)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml/badge.svg)](https://github.com/event4u-app/agent-config/actions/workflows/smoke-public-install.yml) [![npm](https://img.shields.io/npm/v/@event4u/agent-config?style=flat-square&label=npm&color=orange)](https://www.npmjs.com/package/@event4u/agent-config) [![agent-config MCP server](https://glama.ai/mcp/servers/event4u-app/agent-config/badges/score.svg)](https://glama.ai/mcp/servers/event4u-app/agent-config)
 
 > **Choose your experience — developer · founder · content · agency · finance · ops. Add packs. Get a focused command set, not a 500-artefact dump.** Bring your own AI provider.
 
@@ -26,13 +26,40 @@ six entries, no role-detection guesswork.
 **Not sure which one?** Run `npx @event4u/agent-config init` then
 `agent-config setup` — the browser wizard asks a single 8-option role
 question and maps to the closest profile. Source-of-truth:
-[`packages/core/.agent-src.uncondensed/profiles/`](packages/core/.agent-src.uncondensed/profiles/) ·
+[`src/agent-src/profiles/`](src/agent-src/profiles/) ·
 schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
-Beyond software: [`user-types/`](packages/core/.agent-src.uncondensed/user-types/)
+Beyond software: [`user-types/`](src/agent-src/user-types/)
 (galabau · metalworking · truck — see [Beyond software](#beyond-software).
 
+**Per-profile experience pages** (who it's for · first tasks · packs + flows ·
+what is *not* loaded · examples):
+[developer](docs/experiences/developer.md) ·
+[content_creator](docs/experiences/content_creator.md) ·
+[founder](docs/experiences/founder.md) ·
+[agency](docs/experiences/agency.md) ·
+[finance](docs/experiences/finance.md) ·
+[ops](docs/experiences/ops.md).
+
+### Workflows, not raw commands
+
+You don't memorize 150 commands — you run a **work journey**. Four flows span the
+developer story end-to-end; each names the command you TYPE to start and the
+skills it composes:
+
+| Flow | Start with | The journey |
+|---|---|---|
+| 🔍 **Discovery** | `/feature:plan` · `/research` | explore → plan → estimate → refine, *before* building |
+| 🔨 **Implementation** | `/work` · `/implement-ticket` | plan → implement → verify → commit |
+| 🔎 **Review** | `/review-changes` · `/judge` | self-review → judge → quality-fix → threat-model |
+| 🚢 **Delivery** | `/commit` · `/pr:create` | commit in chunks → open PR → answer review |
+
+Full detail — entry commands, canonical path, composed skills per flow:
+[`docs/flows.md`](docs/flows.md). (`agent-admin` — memory / analytics / config —
+is platform operation, not a user-work flow.)
+
 <p align="center">
   <a href="CHANGELOG.md">CHANGELOG</a> ·
+  <a href="MIGRATION.md">Upgrade to 6.0</a> ·
   <a href="CHANGELOG.md#breaking--v400-unified-setup-road-to-unified-setup">Breaking changes</a> ·
   <a href="https://github.com/event4u-app/agent-config/releases/latest">Latest release</a> ·
   <a href="https://github.com/event4u-app/agent-config/discussions">Discussions</a>
@@ -49,7 +76,7 @@ Beyond software: [`user-types/`](packages/core/.agent-src.uncondensed/user-types
 <details>
 <summary><b>Catalog at a glance</b> — raw artefact counts (maintainer reference)</summary>
 
-[![Skills](https://img.shields.io/badge/Skills-223-orange?style=flat-square)](.agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-79-orange?style=flat-square)](.agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-150-orange?style=flat-square)](.agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-73-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-orange?style=flat-square)](.agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](.agent-src/personas/advisors/)
+[![Skills](https://img.shields.io/badge/Skills-227-orange?style=flat-square)](dist/agent-src/skills/) [![Rules](https://img.shields.io/badge/Rules-79-orange?style=flat-square)](dist/agent-src/rules/) [![Commands](https://img.shields.io/badge/Commands-150-orange?style=flat-square)](dist/agent-src/commands/) [![Guidelines](https://img.shields.io/badge/Guidelines-78-orange?style=flat-square)](docs/guidelines/) [![Personas](https://img.shields.io/badge/Personas-24-orange?style=flat-square)](dist/agent-src/personas/) [![Advisors](https://img.shields.io/badge/Advisors-5-orange?style=flat-square)](dist/agent-src/personas/advisors/)
 
 The headline is the **experience** (profile + packs), not the raw counts. Full catalog: [`docs/catalog.md`](docs/catalog.md).
 </details>
@@ -63,11 +90,7 @@ shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
 lists the end-to-end workflows (`/implement-ticket`, `/work`,
 `/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo--implement-ticket).
 
-**Install scope.** Pick **one** scope per machine — project-local (default, recommended for application repos) or user-global (recommended for tooling repos / dotfiles). The installer refuses cross-scope drift via the `scope_guard` pre-flight. Contract: [`docs/contracts/install-scopes.md`](docs/contracts/install-scopes.md). Cleanup when needed: `bash scripts/cleanup_other_scope.sh --confirm`.
-
-## Harness expectations
-
-Three classes of behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (`codex:*`, `cc-gemini-plugin:*`), deferred tools surfaced via `ToolSearch`, and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). First step when a skill appears twice: `task probe:skills`.
+**Install scope.** Pick **one** scope per machine — project-local (default, recommended for application repos) or user-global (recommended for tooling repos / dotfiles). The installer refuses a second, conflicting scope via the `scope_guard` pre-flight. Details: [`docs/contracts/install-scopes.md`](docs/contracts/install-scopes.md). Cleanup when needed: `bash scripts/cleanup_other_scope.sh --confirm`.
 
 ## Prove it
 
@@ -83,7 +106,7 @@ Working on the package itself? [Development](#development) covers the
 `task ci` pipeline, [Requirements](#requirements) the toolchain,
 [Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
 opt-in measurement loop. Source-of-truth tree is
-`packages/core/.agent-src.uncondensed/`; never hand-edit `.augment/` or `.agent-src/`.
+`src/` (`src/skills`, `src/rules`, `src/agent-src/`); never hand-edit `.augment/` or `dist/agent-src/`.
 
 ---
 
@@ -179,7 +202,7 @@ refine → memory → analyze → plan → implement → test → verify → rep
 
 Any ambiguity halts the flow with numbered options — never a silent guess. Persona comes from `.agent-settings.yml` (`roles.active_role`): `senior-engineer` (default), `qa`, or `advisory` (plan-only).
 
-→ [Command reference](.agent-src/commands/implement-ticket.md) · [Flow contract](docs/contracts/implement-ticket-flow.md)
+→ [Command reference](dist/agent-src/commands/implement-ticket.md) · [Flow contract](docs/contracts/implement-ticket-flow.md)
 
 ### Sibling — `/work` (free-form prompt)
 
@@ -199,13 +222,13 @@ The first pass scores the prompt on five dimensions and routes on the band:
 
 After the band gate, the flow is identical to `/implement-ticket`. Free-form goal → `/work`; ticket payload → `/implement-ticket`.
 
-→ [Command reference](.agent-src/commands/work.md) · [`refine-prompt` skill](.agent-src/skills/refine-prompt/SKILL.md)
+→ [Command reference](dist/agent-src/commands/work.md) · [`refine-prompt` skill](dist/agent-src/skills/refine-prompt/SKILL.md)
 
 **After the run:** `agent-config explain last` reconstructs the trace (route · memory · council · halts · provider) — read-only, PII-scrubbed, offline. [Docs](docs/customization.md#explainability--explain-last)
 
 ### Product UI track
 
-UI-shaped work routes to one of three directive sets — `ui` (full audit→design→apply→review→polish→report), `ui-trivial` (≤ 1 file, ≤ 5 lines: apply→test→report), `mixed` (backend + UI: contract→ui→stitch). Existing-UI audit is a **hard gate** ([`ui-audit-gate`](.agent-src/rules/ui-audit-gate.md)); polish has a 2-round ceiling with a11y precedence. Stack detection → `blade-livewire-flux` / `react-shadcn` / `vue` / `plain`.
+UI-shaped work routes to one of three directive sets — `ui` (full audit→design→apply→review→polish→report), `ui-trivial` (≤ 1 file, ≤ 5 lines: apply→test→report), `mixed` (backend + UI: contract→ui→stitch). Existing-UI audit is a **hard gate** ([`ui-audit-gate`](dist/agent-src/rules/ui-audit-gate.md)); polish has a 2-round ceiling with a11y precedence. Stack detection → `blade-livewire-flux` / `react-shadcn` / `vue` / `plain`.
 
 → [Mental model](docs/ui-track-mental-model.md) (1 page) · [Flow contract](docs/contracts/ui-track-flow.md)
 
@@ -231,7 +254,7 @@ Under the hood: kernel-only · kernel + tier-1 · kernel + tier-1 + tier-2. Deta
 
 | Primitive | Voice | Disclosure |
 |---|---|---|
-| [`personas/*.md`](.agent-src/personas/) | Review-lens (internal critique) | n/a |
+| [`personas/*.md`](dist/agent-src/personas/) | Review-lens (internal critique) | n/a |
 | `.agent-user.md` (project root, gitignored) | The maintainer's own voice — `/post-as:me` | None (you are the author) |
 | [`agents/reference/ghostwriter/<slug>.md`](docs/contracts/ghostwriter-schema.md) (gitignored) | Documented public figure — `/post-as:ghostwriter` | **Mandatory, non-removable** footer |
 
@@ -251,6 +274,8 @@ task mcp:cloud:secret-put    # opt in to bearer-auth (recommended for private de
 
 > **Scope — Lite, not Full.** The Worker serves read-only governance (skills · commands · rules · guidelines · contexts) as MCP prompts and resources, plus small read-only tools (`memory_lookup`, `chat_history_read`, `list_*`). It does **not** execute the ~112 Python scripts (linters, audits, `task ci`, work-engine hooks) — those require local install per [Quickstart](#quickstart).
 
+> The built-in **local stdio** server is listed for discovery in the [Glama MCP Registry](https://glama.ai/mcp/servers/event4u-app/agent-config) (agent developers / contributors; requires a local checkout, not a turnkey install — see [ADR-067](docs/decisions/ADR-067-glama-registry-listing.md)).
+
 ### Deployment posture
 
 | Shape | Status | Path |
@@ -275,6 +300,10 @@ npm install --save-dev @event4u/agent-memory
 
 ---
 
+## Harness expectations
+
+Three classes of install/runtime behaviour look like package bugs but are host-harness behaviour the package cannot control — sibling-plugin namespaces (`codex:*`, `cc-gemini-plugin:*`), deferred tools surfaced via `ToolSearch`, and cross-scope skill drift (real bug, fixed in the distribution-channels track). Diagnostics + the package's response: [`docs/contracts/harness-expectations.md`](docs/contracts/harness-expectations.md). First step when a skill appears twice: `task probe:skills`.
+
 ## Supported tools
 
 ### Project-installed (`npx`)
@@ -336,13 +365,13 @@ Stack-agnostic governance core (orchestration · role modes · command clusters
 
 ### Beyond software
 
-The same orchestration core drives non-software trades via [`user-types/`](packages/core/.agent-src.uncondensed/user-types/): [`galabau-field-crew`](packages/core/.agent-src.uncondensed/user-types/galabau-field-crew.md) · [`metalworking-shop`](packages/core/.agent-src.uncondensed/user-types/metalworking-shop.md) · [`truck-driver`](packages/core/.agent-src.uncondensed/user-types/truck-driver.md). Contribute your own — [5-minute scaffold](packages/core/.agent-src.uncondensed/user-types/_template/).
+The same orchestration core drives non-software trades via [`user-types/`](src/agent-src/user-types/): [`galabau-field-crew`](src/agent-src/user-types/galabau-field-crew.md) · [`metalworking-shop`](src/agent-src/user-types/metalworking-shop.md) · [`truck-driver`](src/agent-src/user-types/truck-driver.md). Contribute your own — [5-minute scaffold](src/agent-src/user-types/_template/).
 
 ---
 
 ## Data governance & domain safety
 
-Three domain-safety rules ([`domain-safety-pii`](packages/core/.agent-src.uncondensed/rules/domain-safety-pii.md), [`domain-safety-disclaimer`](packages/core/.agent-src.uncondensed/rules/domain-safety-disclaimer.md), [`domain-safety-retention`](packages/core/.agent-src.uncondensed/rules/domain-safety-retention.md)) act as per-domain output floors across ~12 areas — PII redaction (support / finance / recruiting / marketing), advice disclaimers (legal / financial / medical / consulting), retention guidance (finance / support), ops floors (logging / export). Full surface → rule → floor matrix: [`docs/safety.md`](docs/safety.md). Beta contracts: [`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) · [`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
+Three domain-safety rules ([`domain-safety-pii`](src/rules/domain-safety-pii.md), [`domain-safety-disclaimer`](src/rules/domain-safety-disclaimer.md), [`domain-safety-retention`](src/rules/domain-safety-retention.md)) act as per-domain output floors across ~12 areas — PII redaction (support / finance / recruiting / marketing), advice disclaimers (legal / financial / medical / consulting), retention guidance (finance / support), ops floors (logging / export). Full surface → rule → floor matrix: [`docs/safety.md`](docs/safety.md). Beta contracts: [`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) · [`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
 
 ### Maintainer telemetry (opt-in, default-off)
 
@@ -376,16 +405,16 @@ When a prompt matches a command's purpose ("setze ticket ABC-123 um" → `/imple
 | [**Migration**](docs/MIGRATION.md) | Per-version upgrade steps |
 | [**Showcase**](docs/showcase.md) | More examples & expected behavior |
 
-Browse content: [all 150 commands](.agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
+Browse content: [all 150 commands](dist/agent-src/commands/) · [skills catalog](docs/skills-catalog.md) · [full catalog](docs/catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 
 ## Development
 
-Working on the package itself? Edit `packages/core/.agent-src.uncondensed/`, regenerate trees:
+Working on the package itself? Edit `src/` (the source of truth — `src/skills`, `src/rules`, `src/agent-src/`), regenerate trees:
 
 ```bash
-task sync             # regenerate .agent-src/ and .augment/
+task sync             # regenerate dist/agent-src/ and .augment/
 task generate-tools   # regenerate .claude/, .cursor/, .clinerules/, .windsurfrules
 task ci               # full pipeline — green before PR
 task test             # unit + integration tests

package/dist/agent-src/README.md

@@ -0,0 +1,64 @@
+# Agent Infrastructure
+
+> **⚠️ DO NOT edit files in `dist/agent-src/` or `.augment/` directly.**
+> The source of truth is `.agent-src.uncondensed/`. Edit there, then run `task sync`.
+> See `.agent-src.uncondensed/commands/condense.md` for the full workflow.
+
+This directory contains the shared agent infrastructure: skills, commands, rules, guidelines,
+templates, and contexts that power the AI coding assistant across all projects.
+
+In the package repo, this content lives in `dist/agent-src/` (shipped). Consumer projects install
+it as `.augment/` (local projection).
+
+## Directory Structure
+
+```
+├── commands/       # Slash commands — executable workflows (/fix-pr-comments, /agent-handoff, ...)
+├── contexts/       # Background context documents for the agent
+├── guidelines/     # Coding guidelines by language (reference material)
+├── rules/          # Always-active behavior rules (auto-loaded every conversation)
+├── skills/         # On-demand expertise (matched by topic)
+└── templates/      # File templates for roadmaps, features, skills, etc.
+```
+
+## How It Works
+
+| Layer | Always active? | Purpose |
+|---|---|---|
+| **Rules** | ✅ Yes | Behavior constraints — loaded every conversation |
+| **Skills** | 🔄 On demand | Expertise — matched when the topic is relevant |
+| **Commands** | ⚡ On trigger | Workflows — triggered by `/command-name` |
+| **Guidelines** | 📖 Reference | Coding conventions — read when writing code |
+| **Templates** | 📄 Blueprints | File structure templates for new documents |
+| **Contexts** | 🧠 Background | System-level context about the infrastructure |
+
+For full details see [augment-infrastructure.md](contexts/augment-infrastructure.md).
+
+## Quick Reference
+
+### Most-used commands
+
+| Command | Purpose |
+|---|---|
+| `/agent-handoff` | Generate context summary for a fresh chat |
+| `/fix-pr-comments` | Fix all open PR review comments |
+| `/quality-fix` | Run PHPStan + Rector and fix errors |
+| `/create-pr` | Create a GitHub PR with description |
+| `/bug-investigate` | Investigate a bug from Jira/Sentry |
+| `/tests-create` | Write tests for current changes |
+
+### Key rules
+
+| Rule | What it enforces |
+|---|---|
+| `verify-before-complete` | Must run tests/PHPStan before claiming "done" |
+| `scope-control` | Don't commit/push without permission, no unasked changes |
+| `token-efficiency` | Redirect output, don't narrate, trust ECS/Rector |
+| `downstream-changes` | After every edit, update ALL callers, tests, imports |
+| `php-coding` | Strict types, getters/setters, observers |
+
+## Project-Level Overrides
+
+Projects can override shared skills, rules, and commands via `agents/overrides/`.
+See [override-system.md](contexts/override-system.md) for details.
+

package/dist/agent-src/commands/agent-handoff.md

@@ -0,0 +1,124 @@
+---
+model_tier: medium
+name: agent-handoff
+pack: meta
+intent: "Generate a session-handoff summary to continue work in a fresh chat"
+routes_to: [agent-docs-writing]
+replaces: []
+tier: 0
+skills: [agent-docs-writing]
+description: Generate a context summary for continuing work in a fresh chat. Replaces the session system.
+suggestion:
+  eligible: true
+  trigger_description: "user asks for an agent handoff, fresh-chat summary, or context-summary to paste into a new chat"
+  trigger_context: "explicit verbatim ask — 'agent handoff', 'agend handoff' (typo), 'fasse für neuen chat zusammen', 'handoff summary', 'context summary for fresh chat'. Never inferred without a direct handoff / summary intent."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# /agent-handoff
+
+Generates a concise handoff prompt the user can paste into a new chat.
+This replaces the old session system — no files to save/load, just a copy-paste prompt.
+
+## Steps
+
+### 1. Gather context
+
+Collect the following from the current conversation:
+
+- **Branch**: `git branch --show-current`
+- **Uncommitted changes**: `git status --short`
+- **Recent commits**: `git log --oneline -5`
+- **Active roadmap**: Check `agents/roadmaps/` for any active roadmap
+- **Task list**: Only include if the user explicitly asks for it (e.g., "/agent-handoff with tasks")
+
+### 2. Generate handoff prompt
+
+Create a fenced code block the user can copy-paste into a new chat:
+
+```
+---
+Branch: {branch}
+Last commit: {hash} {message}
+Roadmap: {roadmap file if active, or "none"}
+---
+
+## Done
+- {1-2 sentences summarizing what was accomplished}
+
+## Open
+- {bullet list of remaining tasks or next steps}
+
+## Key decisions
+- {important decisions made during this conversation}
+
+## Relevant files
+- {list of files that were edited or are important for context}
+```
+
+### 3. Present to user
+
+Show the handoff prompt in a fenced code block and say:
+
+```
+> Copy this into a new chat to continue where we left off.
+```
+
+## Iron Law — output is ALWAYS a fenced code block
+
+```
+THE HANDOFF MUST BE WRAPPED IN A FENCED ```markdown CODE BLOCK
+SO THE USER CAN COPY IT IN ONE CLICK. NEVER RENDER IT AS LIVE
+MARKDOWN. NEVER SPLIT IT ACROSS MULTIPLE BLOCKS.
+```
+
+Use ` ```markdown ` as the fence so consumers get syntax highlighting
+and the inner content is preserved verbatim. Add one short prose line
+above the block (e.g. *"Copy this into a new chat:"*) and nothing
+after — no follow-up questions, no numbered options.
+
+## Detection — when natural-language triggers count as explicit
+
+The user does not need to type `/agent-handoff` literally. Treat as
+explicit invocation when the prompt contains a verbatim mention of:
+
+- `agent handoff` / `agend handoff` (typo) / `handoff`
+- `fresh chat`, `neuer chat`, `for a new chat`
+- `context summary for {fresh,new} chat`
+- `fasse … für … chat zusammen`
+
+A vague *"summarize this conversation"* without handoff/new-chat
+framing → NOT a trigger. Surface `/agent-handoff` as a numbered option,
+do not auto-execute.
+
+## Rules
+
+- **Keep it concise** — the prompt should be <30 lines. More context = more input tokens in the new chat.
+- **Only include actionable info** — skip history, reasoning, and failed attempts.
+- **Branch name is critical** — always include it.
+- **Open tasks are critical** — the new chat needs to know what's left.
+- **Decisions are important** — prevents the new chat from re-asking settled questions.
+- **File list is optional** — only include if the new chat will need to edit specific files.
+- **NEVER render the handoff as live markdown** — see Iron Law above.
+
+## When to use this vs. `agents/runtime/.agent-chat-history`
+
+- `/agent-handoff` is **push-based**: you copy a short summary into the
+  new chat. Works across tools (Augment → Claude Code), across machines,
+  and without any persistent file.
+- `agents/runtime/.agent-chat-history` is **pull-based** and **multi-session**: every
+  session writes its own entries tagged with a 16-char session
+  fingerprint derived from the platform `session_id` (schema v4, see
+  [`chat-history-platform-hooks`](../../agents/settings/contexts/chat-history-platform-hooks.md)).
+  Works only on the same machine and same repo, but captures every
+  phase / decision any session logged. Inspect with `/chat-history show`;
+  pull prior-session context into the current chat verbatim with
+  `/chat-history import`; mine a prior session for project-improving
+  learnings with `/chat-history learn`.
+
+Prefer `/agent-handoff` for planned context switches across tools or
+machines; use `/chat-history import` after a crash or fresh-chat reopen
+on the same workspace to surface prior-session context verbatim.