@event4u/agent-config 1.14.0 → 1.16.0

package/docs/guidelines/agent-infra/language-and-tone-examples.md

@@ -0,0 +1,79 @@
+# language-and-tone — examples and failure modes
+
+> Reference companion to [`.agent-src/rules/language-and-tone.md`](../../.agent-src/rules/language-and-tone.md).
+> Pulled out so the always-active rule stays under its character budget.
+> Linked from the rule via the **Examples** section; agents do not load this file
+> automatically, only when they want concrete demonstrations or are debugging a
+> language-mirroring drift.
+
+## Failure modes to watch for
+
+- Drafting reply in English first, then "translating the intro" → English
+  phrasing with German words. Draft in target language from the first token.
+- Copy-pasting English option labels from `.md` sources without translating.
+- Mixing languages inside a table or bullet list because "the technical term
+  is English" — surrounding prose must still mirror. Keep proper nouns and
+  code identifiers as-is; translate everything else.
+- Assuming English because "the codebase is English" — codebase language ≠
+  conversation language.
+- Mirroring the **open file** the IDE reports — open files are background
+  context, not chat messages.
+- Mirroring the **roadmap or ticket** being executed — artefacts are English
+  by `.md` rule; chat language is whatever the user wrote.
+
+## `.md` example labels — wrong vs correct
+
+The agent translates option labels to the user's language **at runtime**.
+The `.md` source files are the English blueprint — they define WHAT to say,
+not in which language.
+
+**Wrong** (German in `.md`):
+
+```
+> 1. Interaktiv — bei jedem Kommentar nachfragen
+> 2. Automatisch — alle selbstständig abarbeiten
+```
+
+**Correct** (English in `.md`):
+
+```
+> 1. Interactive — ask before each comment
+> 2. Automatic — handle all independently
+```
+
+Same rule applies to: example prompts and questions, template placeholders,
+ASCII art labels in formatted output blocks, table headers and content.
+
+## Quoted user-input examples — same rule, with one labeled exception
+
+Common drift pattern: a rule documents trigger phrases the agent should
+recognize and writes them as quoted German examples inside English prose.
+**Not allowed**, even when demonstrative.
+
+**Wrong** (DE quote embedded in EN prose):
+
+```md
+Single-decision delegation ("für diesen Schritt entscheide du") →
+handle that step autonomously.
+
+A standing "arbeite selbstständig" never lifts the floor.
+```
+
+**Correct** — two ways:
+
+1. **Translate to English.** Trigger recognition is semantic; the agent
+   matches intent across languages regardless of the example.
+   `("you decide for this step")` works as well as the German.
+2. **Use a labeled `DE: … · EN: …` anchor list** when the multilingual
+   nature of recognition is the point:
+
+   ```md
+   - DE: "arbeite selbstständig" · "frag nicht jedes Mal" · "tue es einfach"
+   - EN: "work autonomously" · "don't ask" · "just do it"
+   ```
+
+The labeled-anchor block is the **only** allowed location for German prose
+in an English `.md` file. Body text, example sentences, prompt templates,
+agent-rendered strings, and failure modes must be English. Reference
+established phrases abstractly later (e.g. "a standing autonomy directive")
+and link back to the anchor block.

package/{.agent-src → docs}/guidelines/docs/readme-size-and-splitting.md

@@ -2,11 +2,12 @@
 
 ## Purpose
 
-Keep READMEs scannable as repositories grow. A README is an **entry
-point**, not a reference manual. Once it stops working as entry point,
-split — don't scroll.
+Keep READMEs scannable and useful as repositories grow. A README is an
+**entry point**, not a reference manual. Once it stops working as an entry
+point, split — don't scroll.
 
-Referenced by `readme-writing`, `readme-writing-package`, `readme-reviewer`.
+This guideline is referenced by the `readme-writing`, `readme-writing-package`,
+and `readme-reviewer` skills.
 
 ---
 
@@ -41,8 +42,8 @@ Hard triggers — split immediately:
 Soft triggers — review and probably split:
 
 - A section needs its own Table of Contents
-- Reader scrolls past three screens to reach "how do I use it"
-- More than one code block per section explaining variations of the same
+- A reader has to scroll past three screens to reach "how do I use it"
+- More than one code block per section, explaining variations of the same
   thing (indicates reference material, not onboarding)
 
 ---
@@ -64,8 +65,8 @@ README stays < 200 lines. Each `/docs/` file is a self-contained chapter.
 
 ### Strategy 2 — Deep-link tables for multi-platform repos
 
-Supporting many platforms or tool integrations: single table with deep
-links beats inline blocks:
+When supporting many platforms or tool integrations, a single table with
+deep links beats inline blocks:
 
 ```markdown
 | Tool    | Install                | Docs                    |
@@ -78,8 +79,8 @@ Pattern: 1 row per platform, actual how-to in the linked doc.
 
 ### Strategy 3 — Collapsible sections (`<details>`)
 
-Content occasionally needed but crowding the scan path — long install
-options, platform-specific quirks, troubleshooting trees:
+For content that is occasionally needed but crowds the scan path — long
+install options, platform-specific quirks, troubleshooting trees:
 
 ```markdown
 <details>
@@ -90,8 +91,8 @@ Content here — full detail, not shown by default.
 </details>
 ```
 
-Use sparingly. Collapsed content is still in the file; it defers visual
-cost only. Not a substitute for true splitting when content > 30 lines.
+Use sparingly. Collapsed content is still in the file; it just defers the
+visual cost. Not a substitute for true splitting when content is > 30 lines.
 
 ---
 
@@ -104,15 +105,15 @@ Add a ToC when:
 - Reader would need to scroll to find a known section
 
 Place the ToC **after** the one-line summary and **before** the first
-substantive section (usually install or quickstart). Don't add a ToC to
-small READMEs — becomes visual noise.
+substantive section (usually install or quickstart). Do not add a ToC to
+small READMEs — it becomes visual noise.
 
 ---
 
 ## Multi-audience repos
 
 A single README cannot serve "consumers of a package" and "contributors
-to a package" equally. Choose one primary audience for the README,
+to a package" equally well. Choose one primary audience for the README,
 deep-link the other:
 
 - **Package repo** → consumers primary; contributors go to
@@ -120,8 +121,8 @@ deep-link the other:
 - **Application repo** → contributors/team primary; end users (if any)
   go to `docs/user-guide.md`
 
-README must declare its audience within the first screen. Readers in the
-other audience must find their link within the first screen too.
+The README must declare its audience within the first screen. Readers
+in the other audience must find their link within the first screen too.
 
 ---
 
@@ -129,13 +130,13 @@ other audience must find their link within the first screen too.
 
 - **Splitting by accident** — moving content out "because the README is long"
   without a navigation story. Readers get lost.
-- **Splitting and duplicating** — same content in README and `/docs/`.
-  They drift apart. Pick one home.
-- **Deep-link-only README** — README that is just a table of contents
-  linking out. Reader arriving cold must still learn what/why/how-install
+- **Splitting and duplicating** — keeping the same content in README and
+  `/docs/`. They drift apart. Pick one home.
+- **Deep-link-only README** — a README that is just a table of contents
+  linking out. A reader arriving cold must still learn what/why/how-install
   without clicking.
-- **Premature splitting** — `docs/` scaffolding for a 50-line README.
-  Overhead not worth it; come back at 150 lines.
+- **Premature splitting** — creating `docs/` scaffolding for a 50-line
+  README. The overhead is not worth it; come back at 150 lines.
 - **Hiding critical content in `<details>`** — install, first example, and
   requirements are **never** collapsed.
 
@@ -144,10 +145,10 @@ other audience must find their link within the first screen too.
 ## Validation checklist
 
 - [ ] First screen answers what / why / install
-- [ ] Size below "overloaded" threshold, or splitting is in place
+- [ ] Size is below the "overloaded" threshold, or splitting is in place
 - [ ] ToC present if > 150 lines or > 6 top-level sections
 - [ ] No duplication between README and `/docs/`
 - [ ] `<details>` used only for secondary, bulky content
 - [ ] Multi-platform install uses a table, not 10 sequential install blocks
 - [ ] Each `/docs/` file is self-contained and linked from README
-- [ ] Audience explicit; other audience has a visible deep-link
+- [ ] Audience is explicit; the other audience has a visible deep-link

package/docs/guidelines/php/git.md

@@ -0,0 +1,164 @@
+# Git & Version Control Guidelines
+
+> Project-specific Git conventions. Branch naming, commit messages, PR workflow.
+
+**Related Skills:** `git-workflow`, `conventional-commits-writing`
+**Related Rules:** `commit-conventions.md`
+
+## Branch Naming
+
+```
+{type}/{ticket-id}/{short-description}
+```
+
+| Type | When |
+|---|---|
+| `feat/` | New feature |
+| `fix/` | Bug fix |
+| `hotfix/` | Urgent production fix |
+| `chore/` | Maintenance, refactoring, tooling |
+| `docs/` | Documentation changes |
+| `test/` | Test additions/changes |
+
+### Examples
+
+```
+feat/DEV-1234/user-notification-preferences
+fix/DEV-5678/null-pointer-in-import
+chore/refactor-agent-setup
+hotfix/DEV-999/critical-payment-bug
+```
+
+### Rules
+
+- Always include the Jira ticket ID when one exists
+- Use kebab-case for the description part
+- Keep branch names short but descriptive
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+See `commit-conventions` rule for the base format and type table.
+
+### Type selection rules
+
+**`feat`** — a new capability is added; user or system can do something new.
+
+**`fix`** — existing behavior was wrong; bug, regression, or broken edge case corrected.
+
+**`refactor`** — structure changes, readability/maintainability improves, behavior unchanged.
+Do NOT use `refactor` if behavior changes — use `feat` or `fix` instead.
+
+**`docs`** — only documentation changes, no runtime or behavior change.
+
+**`test`** — only tests added/updated, no production behavior changes.
+
+**`ci`** — GitHub Actions, pipelines, CI checks, automation workflows, release jobs.
+
+**`chore`** — maintenance, repo housekeeping, dependency bumps, non-functional cleanup
+that is not better classified as `build`, `ci`, or `docs`.
+
+**`perf`** — measurable performance improvement.
+
+**`build`** — build tooling, packaging, Docker changes.
+
+**`style`** — formatting only, no logic change (e.g. ECS/Rector auto-fixes).
+
+### Scope guidance
+
+Use a scope when it adds clarity. Good scopes:
+
+- Jira ticket ID: `DEV-1234`
+- Module/area: `api`, `auth`, `skills`, `rules`, `ci`, `frontend`, `linter`
+
+Do not add a scope if it adds no value. `fix(core): fix typo` → just `fix: fix typo`.
+
+### Description rules
+
+- Describe **intent**, not implementation detail
+- Describe **what changed**, not every low-level step
+- Avoid generic wording: `update stuff`, `fix issue`, `changes`
+
+Good: `fix(routes): preserve middleware order for api endpoints`
+Bad: `fix: fix things`
+
+### Breaking changes
+
+Use `!` after type/scope or `BREAKING CHANGE:` in footer:
+
+```
+feat(api)!: rename invoice status values
+refactor(auth)!: remove legacy session flow
+```
+
+### Commit splitting
+
+If a change contains multiple unrelated concerns, split into multiple commits.
+
+Bad: `refactor: cleanup skills and fix ci and update docs`
+
+Better:
+```
+refactor(skills): remove duplicate routing helpers
+ci(lint): add skill-lint workflow
+docs(readme): document new lint tasks
+```
+
+### Squash merge titles
+
+- Use Conventional Commit format
+- Summarize the **net effect** of the PR
+- Do not copy vague branch names
+- Do not include issue noise if it hurts readability
+
+### Examples by area
+
+```bash
+# Features
+feat(DEV-2133): send email to customer when product is shipped
+
+# Bug fixes
+fix(import): handle null values in equipment JSON
+
+# Refactoring
+refactor: extract user sync logic into dedicated service
+
+# Skills / Rules / Agent config
+refactor(skills): merge duplicate analysis skills
+feat(rules): add analysis routing quality gate
+fix(skills): restore concrete validation in skill reviewer
+
+# CI / Tooling
+ci(lint): add skill linter workflow
+feat(linter): detect pointer-only skills
+
+# Docs
+docs(roadmap): add phase 3 implementation plan
+docs(readme): clarify source-of-truth workflow
+```
+
+### Decision checklist
+
+Before writing the commit message:
+
+1. Did behavior change? → `feat` or `fix`
+2. Was it only structure/cleanup? → `refactor`
+3. Was it only docs, tests, or CI? → `docs`, `test`, `ci`
+4. Is the scope useful or just noise?
+5. Is this actually multiple commits hiding in one?
+
+### Anti-patterns
+
+- `update stuff` / `fix bug` / `changes` / `refactor everything`
+- Using `chore` for meaningful behavior changes
+- Using `refactor` for bug fixes
+- Using one commit for multiple unrelated concerns
+- Vague squash merge titles that don't describe the net effect
+
+## Pull Requests
+
+- PR title follows commit message format: `feat(DEV-1234): short description`
+- Fill in the PR template (checklist, description, testing notes)
+- Link the Jira ticket in the PR description
+- Ensure all quality gates pass before requesting review
+

package/docs/installation.md

@@ -23,6 +23,23 @@ No Task, no Make, no build tools required for installation.
 | **Project-installed** (recommended) | Teams, shared standards | Repository-wide |
 | **Plugin-installed** | Individual users, global use | User-wide |
 
+> **All paths on this page are still supported.** The labels
+> (`advanced` / `experimental` / `staged`) describe how prominent the
+> path is in our recommendation order, not its support status.
+> Composer + npm are the default; everything else stays shipped and
+> tested. Nothing on this page is being removed in 1.15.0 — the
+> reorder simply marks which paths get the most maintenance attention
+> and which we keep as fallbacks. See R9 in
+> [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../agents/roadmaps/archive/road-to-post-pr29-optimize.md)
+> for the rationale.
+
+| Label | Meaning | Examples |
+|---|---|---|
+| (no label) | Primary path — first-class, fully supported | Composer, npm, Augment / Claude Code / Copilot CLI plugins |
+| `advanced` | Supported fallback — works, expects familiarity with the toolchain | Git submodule, manual clone, VS Code Git URL |
+| `experimental` | Shipped but evolving — interface may shift between minor releases | Claude.ai Web Skills UI |
+| `staged` | Shipped, narrow surface area — kept for users who already use the platform | Linear AI workspace guidance |
+
 ---
 
 ## Project-installed mode (recommended for teams)
@@ -210,7 +227,16 @@ These channels are **additional** to project- and plugin-installed
 modes; use them when the agent loop runs on the platform's servers,
 not on your machine.
 
-### Claude.ai Web (Skills UI)
+> Both cloud channels remain shipped and tested. The labels reflect
+> recommendation prominence, not support status — see the label table
+> at the top of this page.
+
+### Claude.ai Web (Skills UI) — `experimental`
+
+> `experimental` — shipped, still tested, but the upload surface and
+> bundle format may shift between minor releases as Claude.ai's Skills
+> UI evolves. Pin to a release tag if you depend on a specific bundle
+> shape.
 
 Claude.ai Web supports Skills via manual ZIP upload through the Skills
 UI. The package builds one ZIP per cloud-eligible skill.
@@ -238,7 +264,12 @@ UI. The package builds one ZIP per cloud-eligible skill.
 3. **Verify** — open a fresh Claude.ai conversation and confirm the
    skill appears in the Skills picker.
 
-### Linear AI (Codegen, Charlie, …)
+### Linear AI (Codegen, Charlie, …) — `staged`
+
+> `staged` — shipped, narrow surface area, kept primarily for users
+> already operating inside Linear. Iteration cadence is slower than
+> the project- and plugin-installed paths; major changes land first
+> on Composer + npm and propagate to the Linear digest in a follow-up.
 
 Linear AI agents read free-form guidance from Linear's workspace
 settings; there is no plugin or upload mechanism. The package ships
@@ -264,16 +295,21 @@ the matching Linear field.
    - Leave `personal.md` empty unless you have personal overrides
 
 3. **Per-layer rationale** — see
-   [`agents/contexts/linear-ai-three-layers.md`](../agents/contexts/linear-ai-three-layers.md)
+   [`docs/contracts/linear-ai-three-layers.md`](contracts/linear-ai-three-layers.md)
    for the split rationale and
-   [`agents/contexts/linear-ai-rules-inclusion.md`](../agents/contexts/linear-ai-rules-inclusion.md)
+   [`docs/contracts/linear-ai-rules-inclusion.md`](contracts/linear-ai-rules-inclusion.md)
    for which rules go where.
 
 ---
 
-## Alternative install methods
+## Alternative install methods — `advanced`
 
-These are fallbacks when the recommended paths above don't work.
+> `advanced` — supported fallbacks for users comfortable driving the
+> orchestrator directly. They share the same `scripts/install` entry
+> point as Composer and npm; the only difference is how the package
+> source ends up on disk. Pick these when you cannot use Composer or
+> npm (e.g. a polyglot repo without either, or a CI runner that
+> already vendors the package via submodule).
 
 ### Git Submodule
 

package/docs/migrations/commands-1.15.0.md

@@ -0,0 +1,112 @@
+# Command migration — 1.15.0
+
+> **Audience:** consumers of `event4u/agent-config` upgrading from
+> `1.14.x` to `1.15.0`.
+> **Authoritative spec:** [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md).
+
+`1.15.0` collapses 15 atomic commands into 3 verb clusters
+(`fix`, `optimize`, `feature`) to reduce command-palette
+fragmentation. **Old commands keep working through the entire
+1.15.x cycle**; they emit a one-line deprecation warning on
+invocation and are removed in `1.16.0`.
+
+## Summary table
+
+| 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-portability` | `/fix portability` | 1.16.0 |
+| `/fix-references` | `/fix refs` | 1.16.0 |
+| `/fix-seeder` | `/fix seeder` | 1.16.0 |
+| `/optimize-agents` | `/optimize agents` | 1.16.0 |
+| `/optimize-augmentignore` | `/optimize augmentignore` | 1.16.0 |
+| `/optimize-rtk-filters` | `/optimize rtk` | 1.16.0 |
+| `/optimize-skills` | `/optimize skills` | 1.16.0 |
+| `/feature-explore` | `/feature explore` | 1.16.0 |
+| `/feature-plan` | `/feature plan` | 1.16.0 |
+| `/feature-refactor` | `/feature refactor` | 1.16.0 |
+| `/feature-roadmap` | `/feature roadmap` | 1.16.0 |
+
+## What changes for you
+
+**Nothing breaks in 1.15.x.** Old slugs continue to work — the agent
+recognises them, dispatches to the new cluster command, and prints
+one warning line at the top of the reply:
+
+```
+⚠️  /fix-ci is deprecated; use /fix ci instead.
+```
+
+**Your existing custom skills, rules, or agents/roadmaps that
+reference old slugs do not need to change in 1.15.x.** Update at
+your own pace.
+
+## What to update before 1.16.0
+
+Search your project for any direct references to the old slugs and
+swap them for the new invocation:
+
+```bash
+# Find references in agents/, docs/, README, custom rules
+rg -n '/(fix|optimize|feature)-[a-z-]+' \
+   agents/ docs/ README.md AGENTS.md .github/ 2>/dev/null
+```
+
+Common spots:
+
+- `agents/roadmaps/*.md` — roadmap steps that name commands
+- `agents/contexts/*.md` — context docs cross-linking commands
+- Custom skills/rules under `.augment/` overrides
+- Internal team docs / runbooks / onboarding pages
+
+## Why this changed
+
+The atomic-command surface had grown to 77 commands by 1.14.0. Three
+prefix families (`fix-*`, `optimize-*`, `feature-*`) accounted for 15
+of those — same verb, same invocation pattern, only the noun
+differed. Collapsing the families into clusters:
+
+- Reduces palette noise (15 → 3 top-level entries).
+- Makes new sub-commands additive (`/fix tests` ships without a new
+  top-level slug).
+- Holds the line: `scripts/lint_no_new_atomic_commands.py` fails CI
+  if a new atomic command lands without a `cluster:` field declared
+  in [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md).
+
+## Phase 2 (deferred)
+
+A second wave of collapses (`chat-history`, `agents`, `memory`,
+`roadmap`, `module`, `tests`, `context`, `override`, `copilot-agents`,
+`commit`, `judge`, `create-pr`) is scheduled after 1.15.0 ships and
+the deprecation cycle for Phase 1 closes. Tracked in
+[`agents/roadmaps/archive/road-to-governance-cleanup.md`](../../agents/roadmaps/archive/road-to-governance-cleanup.md)
+§ F2.
+
+## Related rule split — `chat-history` (post-1.15.0)
+
+The monolithic `rules/chat-history.md` was split into three sibling
+`always` rules in the post-1.15.0 optimization phase:
+
+- [`chat-history-ownership`](../../.agent-src/rules/chat-history-ownership.md) — sole owner of file I/O + first-turn handshake.
+- [`chat-history-cadence`](../../.agent-src/rules/chat-history-cadence.md) — when to persist (SessionStart / StepEnd / append boundaries).
+- [`chat-history-visibility`](../../.agent-src/rules/chat-history-visibility.md) — heartbeat marker contract for user-facing reporting.
+
+Decision record: [`docs/contracts/adr-chat-history-split.md`](../contracts/adr-chat-history-split.md).
+Cross-references in commands and contexts now point to
+`chat-history-ownership` as the entry point.
+
+## Rollback
+
+If a deprecation warning blocks tooling that screen-scrapes agent
+output, suppress it for the 1.15.x cycle by setting
+`commands.deprecation_warnings: false` in `.agent-settings.yml`.
+The setting disappears in 1.16.0 along with the shims.
+
+## See also
+
+- [`docs/contracts/command-clusters.md`](../contracts/command-clusters.md) — locked cluster spec.
+- [`docs/contracts/STABILITY.md`](../contracts/STABILITY.md) — public-surface stability tiers.
+- [`agents/roadmaps/archive/road-to-post-pr29-optimize.md`](../../agents/roadmaps/archive/road-to-post-pr29-optimize.md) — P0.8 anchor for this migration.

package/docs/showcase.md

@@ -192,10 +192,15 @@ criteria, assumptions, confidence band) before the engine plans.
 
 ## More
 
-The five examples above cover the load-bearing iron laws. The full
-rule set lives in [`.agent-src/rules/`](../.agent-src/rules/) (browse
-the `description:` line in each file's frontmatter to see when it
-auto-triggers); the full skill catalog is in
+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 [`.agent-src/rules/`](../.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