@event4u/agent-config 2.13.0 → 2.15.0

package/.agent-src/commands/agents/user/accept.md

@@ -0,0 +1,117 @@
+---
+name: agents:user-accept
+tier: 2
+cluster: agents
+sub: user
+description: Apply a buffered observation to .agent-user.md after explicit user confirmation; bumps last_updated and drops the applied observations from the buffer.
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Mutates .agent-user.md — only run from /agents user review or explicit user invocation."
+---
+
+# /agents user accept
+
+Apply a buffered observation from
+[`.agent-user.observations.jsonl`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer)
+to `.agent-user.md` after explicit confirmation.
+
+Use when:
+
+- `/agents user review` surfaced an observation worth applying.
+- The user invoked `/agents user accept <field>` directly.
+
+Never runs autonomously — always asks before writing.
+
+## Steps
+
+### 1. Preconditions
+
+```bash
+ls .agent-user.md 2>/dev/null
+ls .agent-user.observations.jsonl 2>/dev/null
+```
+
+Either missing → print "Run `/agents user init` and accumulate
+observations first." and stop.
+
+### 2. Resolve target field
+
+| Invocation | Resolved field |
+|---|---|
+| Handed off from `/agents user review` option 1 | The most-frequent field |
+| `/agents user accept <field>` | `<field>` (must match the schema enum) |
+| `/agents user accept` with no arg | Print the field list, ask which |
+
+Invalid field → print the schema enum and stop.
+
+### 3. Compute proposed change
+
+For the resolved field:
+
+1. Read every matching observation from the buffer.
+2. Pick the **latest** `suggest` value (most recent `ts` wins).
+3. Read the current value from `.agent-user.md`.
+4. If they match, print "No change — current value already matches
+   the latest observation." and skip to step 6.
+
+### 4. Confirm
+
+```
+Apply this change to .agent-user.md?
+
+  field   : {field}
+  current : "{current_value}"
+  proposed: "{proposed_value}"
+  source  : {n} observations between {oldest_ts} and {newest_ts}
+  evidence: {latest_evidence, truncated to 200 chars}
+
+> 1. Apply
+> 2. Skip — keep current value, drop these observations from the buffer
+> 3. Cancel — leave .agent-user.md and buffer untouched
+```
+
+One question per turn. Wait for the user's number.
+
+### 5. Write
+
+On `1. Apply`:
+
+1. Rewrite the targeted field in `.agent-user.md` frontmatter.
+   Preserve every other field byte-for-byte (use a YAML round-trip
+   loader that keeps formatting).
+2. Bump `last_updated` to today (ISO `YYYY-MM-DD`).
+3. Validate the result: schema present, ≤100 lines, privacy floor
+   clean. Any violation → roll back and print the error.
+4. Drop **all** applied observations for that field from the buffer
+   (rewrite the JSONL minus matching lines).
+
+On `2. Skip`: leave `.agent-user.md` untouched but still drop the
+observations for that field from the buffer.
+
+On `3. Cancel`: stop without any write.
+
+### 6. Confirm
+
+```
+✅  .agent-user.md updated ({field}: "{old}" → "{new}", last_updated: YYYY-MM-DD).
+   Buffer: {n} observations removed, {m} remaining.
+```
+
+Do NOT commit. Do NOT auto-chain to a second field.
+
+## Rules
+
+- One field per invocation. The user runs `/agents user accept` again
+  for the next field.
+- Never write without explicit confirmation in step 4.
+- Never bypass the privacy-floor scan, even if the buffer writer
+  already redacted.
+- Mirror the user's language for prompts per
+  [`language-and-tone`](../../../../.agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user review`](review.md), [`/agents user update`](update.md).

package/.agent-src/commands/agents/user/init.md

@@ -0,0 +1,163 @@
+---
+name: agents:user-init
+tier: 2
+cluster: agents
+sub: user
+description: Interactive interview that creates the project-root .agent-user.md from the locked v1 schema (name, language, role, style, voice_sample).
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "User-persona bootstrap — only deliberately, never auto-suggested."
+---
+
+# /agents user init
+
+Short interactive interview that creates **`.agent-user.md`** at the
+project root from the locked v1 schema in
+[`docs/contracts/agent-user-schema.md`](../../../../../docs/contracts/agent-user-schema.md).
+
+Use when:
+
+- The user wants the agent to address them by name / nickname / role.
+- A fresh consumer project does not yet have `.agent-user.md`.
+
+Refuses to overwrite an existing file without `--force`.
+
+## Steps
+
+### 1. Precondition checks
+
+```bash
+ls .agent-user.md 2>/dev/null
+ls docs/contracts/agent-user-schema.md 2>/dev/null
+```
+
+| State | Action |
+|---|---|
+| `.agent-user.md` missing | Proceed |
+| `.agent-user.md` exists, no `--force` | Abort; offer `/agents user update` instead |
+| `.agent-user.md` exists, `--force` set | Proceed (will overwrite); back up to `.agent-user.md.bak` first |
+| Schema contract missing | Abort with "package not installed / out of date" hint |
+
+### 2. Pre-fill from `.agent-settings.yml`
+
+If `.agent-settings.yml` exists, read `personal.user_name` and offer
+it as the default for `identity.name`. Do **not** read anything else —
+the persona file is a separate primitive.
+
+### 3. Interview (one question per turn, numbered options)
+
+Ask in this order. Each answer drives one frontmatter field.
+
+1. **Name** — required.
+   `Wie soll ich dich ansprechen? (Name)` / `What name should I use?`
+   Default: pre-fill from step 2 if available.
+
+2. **Nickname** — optional.
+   `Bevorzugter Spitzname für den Chat? (leer = wie Name)` /
+   `Preferred chat nickname? (blank = same as name)`
+
+3. **Language** — required, BCP-47-ish.
+   ```
+   > 1. de — Deutsch
+   > 2. en — English
+   > 3. other — type the code (e.g. "fr", "es")
+   ```
+   Default: detect from the user's last message.
+
+4. **Role** — required, short free-form.
+   `Kurze Rollenbeschreibung (z. B. "founder/engineer", "product manager", "designer")` /
+   `Short role label`
+
+5. **Style — formality**.
+   ```
+   > 1. informal — Du / first-name (default)
+   > 2. formal   — Sie / full name
+   ```
+
+6. **Style — pace**.
+   ```
+   > 1. pragmatic — balanced (default)
+   > 2. thorough  — more verification, longer replies
+   > 3. rapid     — shorter replies, fewer caveats
+   ```
+
+7. **Voice sample** — required.
+   `Paste eine typische Nachricht von dir (1–3 Sätze, im normalen Schreibstil)` /
+   `Paste one typical message of yours (1–3 sentences, your normal style)`
+
+### 4. Privacy-floor sanity check
+
+Before writing, scan the collected `voice_sample` and `role` for:
+
+- Credentials, API keys, tokens, passwords (regex on common formats).
+- Third-party full names that look like contacts (heuristic: capitalized first+last pair near words like "wife", "boss", "kid", "Frau", "Mann", "Chef").
+- Financial figures (currency symbols + numbers).
+- Health/legal status keywords.
+
+Hit → surface the line and ask the user to redact before proceeding.
+Per [`agent-user-schema § Explicit exclusions`](../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+
+### 5. Render and write
+
+Render the frontmatter exactly as locked in the schema. Add an empty
+`# Notes` body. Set `last_updated` to today (ISO date).
+
+```yaml
+---
+version: 1
+identity:
+  name: "..."
+  nickname: "..."          # omit if blank
+language: "..."
+role: "..."
+style:
+  formality: "..."
+  pace: "...""
+voice_sample: |
+  ...
+last_updated: "YYYY-MM-DD"
+---
+
+# Notes
+```
+
+Verify the rendered file is ≤100 lines (it will be — empty Notes body)
+before writing to `.agent-user.md`.
+
+### 6. Gitignore check
+
+If the consumer `.gitignore` does not yet contain `.agent-user.md`,
+print a one-line nudge:
+
+```
+ℹ️  .agent-user.md is not yet in your .gitignore. Run /sync-gitignore to add it.
+```
+
+The package-managed block adds it automatically; this nudge only
+fires when the block is missing or out of date.
+
+### 7. Confirm
+
+Print the file path and a one-line summary:
+
+```
+✅  .agent-user.md written ({n} lines).
+   identity: {nickname or name} · language: {lang} · role: {role} · style: {formality}/{pace}
+```
+
+Do NOT commit. Do NOT run any other `/agents user` sub-sub-command.
+
+## Rules
+
+- One question per turn. Never batch.
+- Numbered options where the answer is enum-like (per
+  [`user-interaction`](../../../../.agent-src/rules/user-interaction.md)).
+- Never invent fields not in the locked v1 schema.
+- Never write third-party PII even if the user pastes it — surface
+  and ask for redaction.
+
+## See also
+
+- Schema: [`agent-user-schema`](../../../../../docs/contracts/agent-user-schema.md).
+- Parent: [`/agents user`](../user.md).

package/.agent-src/commands/agents/user/review.md

@@ -0,0 +1,107 @@
+---
+name: agents:user-review
+tier: 2
+cluster: agents
+sub: user
+description: List buffered observations from .agent-user.observations.jsonl with numbered options to inspect or accept individually.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "review user observations, see what the agent learned about me, list buffered persona updates"
+  trigger_context: "user wants to see what the agent has buffered about their preferences before applying changes"
+---
+
+# /agents user review
+
+List the buffered observations in `.agent-user.observations.jsonl`
+and let the user choose which to inspect or accept.
+
+Use when:
+
+- You want to see what the agent has learned about your preferences.
+- You suspect `.agent-user.md` is out of date and want a curated
+  diff before editing.
+- You want to dismiss observations the agent collected.
+
+Read-only by itself — actual changes go through
+[`/agents user accept`](accept.md) or
+[`/agents user update`](update.md).
+
+## Steps
+
+### 1. Locate buffer
+
+```bash
+ls .agent-user.observations.jsonl 2>/dev/null
+```
+
+| State | Action |
+|---|---|
+| Missing or empty | Print "No buffered observations. The agent has not learned anything new." and stop |
+| Present | Proceed |
+
+### 2. Parse + group
+
+Read every line as JSON. Drop malformed lines silently (one-line
+warning at the end with the count). Group by `field`:
+
+```
+.agent-user.observations.jsonl — {n} observations across {k} fields
+
+  1. style.pace          ({n}× since {oldest_ts})
+     latest suggest: "rapid" — evidence: user said 'mach kürzer' 3× this session
+  2. identity.nickname   ({n}× since {oldest_ts})
+     latest suggest: "Matze" — evidence: user signed last 3 messages "— Matze"
+  3. language            ({n}× since {oldest_ts})
+     latest suggest: "de" — evidence: last 12 messages in German, .agent-user.md says "en"
+```
+
+Sort by frequency (most observations first), then by recency.
+
+### 3. Ask
+
+```
+> 1. Accept the most-frequent suggestion ({field} → {value})
+> 2. Inspect a specific field
+> 3. Clear the buffer (discard all)
+> 4. Cancel
+```
+
+| Choice | Action |
+|---|---|
+| 1 | Hand off to [`/agents user accept`](accept.md) with the chosen field |
+| 2 | Print every observation for that field with evidence + ts, then re-ask |
+| 3 | Truncate `.agent-user.observations.jsonl` to zero bytes; print confirmation |
+| 4 | Stop without changes |
+
+One question per turn. Wait for the user's number.
+
+### 4. Privacy-floor verify
+
+Before printing any observation's `evidence` text, scan it for the
+[exclusions list](../../../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+Match → replace the offending substring with `[redacted]` in the
+rendered output.
+
+The buffer writer is expected to redact on write, but treat this as
+defense in depth — the user must never see leaked third-party PII or
+credentials from a downstream agent's bad write.
+
+### 5. Stop
+
+Do NOT commit. Do NOT auto-chain past one user-selected action per
+turn.
+
+## Rules
+
+- Read-only on `.agent-user.md`. Only `accept` writes to the persona
+  file.
+- Buffer is the only mutable artefact (truncate via option 3).
+- Mirror the user's language for prompts per
+  [`language-and-tone`](../../../../.agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema + buffer contract: [`agent-user-schema § Observation buffer`](../../../../../docs/contracts/agent-user-schema.md#observation-buffer).
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user accept`](accept.md), [`/agents user update`](update.md).

package/.agent-src/commands/agents/user/show.md

@@ -0,0 +1,109 @@
+---
+name: agents:user-show
+tier: 2
+cluster: agents
+sub: user
+description: Read-only render of .agent-user.md — prints the persona summary the host agent loads at session start.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "show user persona, render .agent-user.md, print who the user is"
+  trigger_context: "user wants to see what's currently in .agent-user.md without editing"
+---
+
+# /agents user show
+
+Read-only render of the project-root `.agent-user.md` per
+[`docs/contracts/agent-user-schema.md`](../../../../../docs/contracts/agent-user-schema.md).
+
+Use when:
+
+- You want to see what persona the host agent currently loads.
+- You want to confirm `last_updated` is fresh (≤90 days).
+- You want a paste-ready summary for handoff or onboarding.
+
+Does **not** edit, observe, or buffer anything. Pure read.
+
+## Steps
+
+### 1. Locate the file
+
+```bash
+ls .agent-user.md 2>/dev/null
+```
+
+| State | Action |
+|---|---|
+| Present | Proceed |
+| Missing | Print "No `.agent-user.md` found at project root. Run `/agents user init` to create one." and stop |
+
+### 2. Parse frontmatter
+
+Parse the YAML frontmatter and the body (everything after the second
+`---`). Validate against the locked v1 schema:
+
+- `version` is `1`.
+- `identity.name`, `language`, `role`, `style.formality`, `style.pace`,
+  `voice_sample`, `last_updated` are all present.
+- File is ≤100 lines total.
+
+Any violation → print a one-line warning identifying the missing /
+malformed field and continue with the render (so the user can fix it
+via `/agents user update`).
+
+### 3. Render
+
+Print the persona in this exact shape:
+
+```
+.agent-user.md  ({n} lines, last_updated: YYYY-MM-DD{staleness_marker})
+
+  Identity   : {nickname or name}  ({name} if nickname is set)
+  Language   : {language}
+  Role       : {role}
+  Style      : {formality} · {pace}
+
+  Voice sample
+  ─────────────
+  {voice_sample, indented 2 spaces}
+
+  Notes
+  ─────────────
+  {body, indented 2 spaces; "(empty)" if no notes}
+```
+
+Where `{staleness_marker}` is:
+
+- empty when `last_updated` is within 90 days.
+- ` ⚠️  >90 days` when older (per the schema staleness rule).
+
+### 4. Loader hint
+
+If the host-agent loader has NOT yet picked up the file this session
+(detect via session memory if available), print one line:
+
+```
+ℹ️  Host agent will load this on next session start. Restart your chat to apply.
+```
+
+Otherwise omit — agent already knows.
+
+### 5. Stop
+
+Do NOT chain to other `/agents user *` commands. Do NOT commit.
+
+## Rules
+
+- Read-only. Never write `.agent-user.md` from this command.
+- Never print fields the schema does not define — even if they exist
+  in the file. (Forward-compat: an unexpected field is a warning, not
+  a render target.)
+- Mirror the user's language for the rendered labels (`Identity` /
+  `Identität`, `Language` / `Sprache`, etc.) per
+  [`language-and-tone`](../../../../.agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema: [`agent-user-schema`](../../../../../docs/contracts/agent-user-schema.md).
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user init`](init.md), [`/agents user update`](update.md).

package/.agent-src/commands/agents/user/update.md

@@ -0,0 +1,98 @@
+---
+name: agents:user-update
+tier: 2
+cluster: agents
+sub: user
+description: Open .agent-user.md in the user's IDE for manual edit; validates schema and 100-line cap on save.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "edit user persona, update .agent-user.md, change nickname, change language, refresh voice sample"
+  trigger_context: "user wants to manually edit the persona file rather than answer interview questions"
+---
+
+# /agents user update
+
+Open `.agent-user.md` in the user's IDE for a manual edit, then
+validate against the locked v1 schema on save.
+
+Use when:
+
+- The user knows exactly what they want to change (nickname, language,
+  voice sample) and doesn't need the interview flow.
+- The user wants to edit the freeform `# Notes` body.
+- `/agents user show` flagged a malformed field.
+
+For agent-driven changes from buffered observations, use
+[`/agents user review`](review.md) → [`/agents user accept`](accept.md).
+
+## Steps
+
+### 1. Precondition
+
+```bash
+ls .agent-user.md 2>/dev/null
+```
+
+Missing → print "No `.agent-user.md` found. Run `/agents user init`
+first." and stop.
+
+### 2. Open in IDE
+
+Use the [`file-editor`](../../../../.agent-src/skills/file-editor/SKILL.md)
+skill — reads `personal.ide` from `.agent-settings.yml` (vscode,
+phpstorm, cursor, etc.) and opens the file.
+
+If `personal.ide` is unset or `auto_open_files: false`, print:
+
+```
+ℹ️  Open .agent-user.md in your editor and re-run /agents user update --validate when done.
+```
+
+### 3. Wait for save → validate
+
+When called with `--validate` (or after the user confirms "done"):
+
+1. Read `.agent-user.md`.
+2. Parse frontmatter; check every required field per
+   [`agent-user-schema § Field reference`](../../../../../docs/contracts/agent-user-schema.md#field-reference).
+3. Check file size ≤100 lines.
+4. Run the privacy-floor scan (same as `init` step 4): credentials,
+   third-party PII, financial figures, health/legal status.
+
+| Result | Action |
+|---|---|
+| All checks pass | Bump `last_updated` to today; print one-line confirmation |
+| Schema violation | Print the offending field + line, ask user to fix |
+| >100 lines | Print line count, ask user to trim |
+| Privacy-floor hit | Print the suspect line, ask user to redact |
+
+### 4. Bump `last_updated`
+
+On successful validation, rewrite the `last_updated` field with
+today's date (ISO `YYYY-MM-DD`). Preserve all other content
+verbatim.
+
+### 5. Confirm
+
+```
+✅  .agent-user.md validated ({n} lines, last_updated: YYYY-MM-DD).
+```
+
+Do NOT commit. Do NOT chain to another `/agents user *` command.
+
+## Rules
+
+- Never edit `.agent-user.md` directly from this command except for
+  the `last_updated` bump in step 4. All other edits go through the
+  user's IDE.
+- Never write third-party PII even if it appears in the user's edit —
+  re-surface and ask for redaction.
+- Mirror the user's language for all prompts per
+  [`language-and-tone`](../../../../.agent-src/rules/language-and-tone.md).
+
+## See also
+
+- Schema: [`agent-user-schema`](../../../../../docs/contracts/agent-user-schema.md).
+- Parent: [`/agents user`](../user.md).
+- Sibling: [`/agents user init`](init.md), [`/agents user show`](show.md), [`/agents user review`](review.md).

package/.agent-src/commands/agents/user.md

@@ -0,0 +1,66 @@
+---
+name: agents:user
+tier: 2
+cluster: agents
+sub: user
+description: User-persona file (.agent-user.md) — interview, render, and maintain who the user is and how they want to be addressed.
+disable-model-invocation: true
+type: orchestrator
+suggestion:
+  eligible: true
+  trigger_description: "create user persona, render .agent-user.md, review observations, accept observations, edit user file"
+  trigger_context: "user wants to bootstrap or maintain the .agent-user.md persona file (name, language, role, style, voice sample)"
+---
+
+# /agents user
+
+Sub-dispatcher for the user-persona file
+[`/.agent-user.md`](../../../docs/contracts/agent-user-schema.md) — a
+single, project-root, gitignored Markdown file that captures who the
+user is and how they want the agent to address them.
+
+**Why this is its own cluster:** `AGENTS.md` describes the *project*
+to the agent. `.agent-user.md` describes the *user* to the agent.
+Two distinct primitives — same `/agents` family for discoverability,
+separate sub-commands for separation of concerns.
+
+## Sub-sub-commands
+
+| Sub-sub-command | Routes to | Purpose |
+|---|---|---|
+| `/agents user init` | `commands/agents/user/init.md` | Short interview → creates `.agent-user.md` |
+| `/agents user show` | `commands/agents/user/show.md` | Read-only render of the persona |
+| `/agents user review` | `commands/agents/user/review.md` | List buffered observations from `.agent-user.observations.jsonl` |
+| `/agents user accept` | `commands/agents/user/accept.md` | Apply a buffered observation with confirmation |
+| `/agents user update` | `commands/agents/user/update.md` | Open in IDE for manual edit; validate on save |
+
+Schema contract:
+[`docs/contracts/agent-user-schema.md`](../../../docs/contracts/agent-user-schema.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/agents user <sub-sub-command> [args]`.
+2. Look up the sub-sub-command in the table above.
+3. Load the routed file and follow its `## Steps` section verbatim
+   with the remaining args.
+4. Unknown or missing sub-sub-command → print the table above and
+   ask which one. **One sub-sub-command per turn**; do not chain.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-sub-command
+  explicitly authorizes it.
+- **Do NOT write third-party PII** — names, dates, financial figures,
+  health/legal status. See the
+  [exclusions list](../../../docs/contracts/agent-user-schema.md#explicit-exclusions).
+- **Do NOT introduce network code** in this package. External
+  enrichment is rejected for v1 — see the
+  [determinism floor](../../../docs/contracts/agent-user-schema.md#determinism-floor).
+- **Edit `.agent-src.uncompressed/` only.** `.agent-src/` and
+  `.augment/` regenerate from source.
+
+## See also
+
+- [`agent-user-schema`](../../../docs/contracts/agent-user-schema.md) — locked v1 frontmatter and field reference.
+- [`/agents`](../AGENTS.md) — parent cluster.
+- [`/agents init`](init.md) — project-side bootstrap (separate primitive).

package/.agent-src/commands/agents.md

@@ -28,6 +28,7 @@ agent infrastructure (rules, skills, pointers).
 | `/agents init` | `commands/agents/init.md` | Bootstrap the agent layer — create `AGENTS.md` + tool stubs from the canonical template |
 | `/agents optimize` | `commands/agents/optimize.md` | Refactor `AGENTS.md` to the Thin-Root contract; propagate to multi-tool stubs |
 | `/agents audit` | `commands/agents/audit.md` | Read-only health check — token overhead, rule triggers, AGENTS.md health, stale references |
+| `/agents user` | `commands/agents/user.md` | User-persona file (`.agent-user.md`) — interview, render, maintenance |
 
 Sub-command names match the locked contract in
 [`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
@@ -43,6 +44,7 @@ Sub-command names match the locked contract in
    > 1. init — bootstrap AGENTS.md + tool stubs
    > 2. optimize — refactor AGENTS.md to the Thin-Root contract
    > 3. audit — read-only health check on the agent layer
+   > 4. user — manage `.agent-user.md` (user-persona file)
 
 ## Rules