@event4u/agent-config 2.18.0 → 2.19.0

package/docs/contracts/adr-mcp-runtime.md

@@ -0,0 +1,128 @@
+---
+stability: stable
+---
+
+# ADR — MCP server runtime: Anthropic `mcp` Python SDK
+
+> **Status:** Decided · 2026-05-10 (recorded 2026-05-15).
+> **Context:**
+> [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md),
+> [`mcp-cloud-scope.md`](mcp-cloud-scope.md).
+
+## Decision
+
+The MCP server at `scripts/mcp_server/` runs on **Python 3.11+** using the
+official Anthropic **`mcp` Python SDK** (PyPI; pinned to `mcp==1.27.1`
+per [`scripts/mcp_server/requirements.txt`](../../scripts/mcp_server/requirements.txt)).
+**FastMCP** (the higher-level decorator wrapper) and the **MCP TypeScript SDK**
+are explicitly rejected for this surface.
+
+The hosted Cloudflare Worker bridge (`workers/mcp/`) is the only place a
+non-Python runtime is allowed, and it stays bound to the same wire contract
+(see [`mcp-cloud-scope.md`](mcp-cloud-scope.md)).
+
+## Why this was a real question
+
+The package already ships Python under `scripts/` (work engine, AI Council,
+skill linter, install driver helpers) and ships zero Node-runtime code paths
+outside the npx dispatcher. Picking a runtime for the MCP server had three
+candidates that all could have shipped:
+
+1. **MCP Python SDK** (low-level `Server` + `stdio_server` handlers).
+2. **FastMCP** (higher-level Pythonic decorators built on the same SDK).
+3. **MCP TypeScript SDK** (Node runtime, separate package).
+
+Without an ADR, this choice would have stayed implicit in the code and
+re-litigated every time a contributor read `scripts/mcp_server/server.py`.
+
+## Why MCP Python SDK (low-level) wins
+
+| Criterion | MCP Python SDK | FastMCP | MCP TypeScript SDK |
+|---|---|---|---|
+| Runtime already in repo | ✅ Python is the `scripts/` runtime | ✅ Same | ❌ Adds Node-runtime path for one server |
+| A0 safety boundary fit (read-only `prompts/list`, `prompts/get`, narrow `tools/*` allowlist) | ✅ Direct handler control matches the [Phase 1 scope contract](mcp-phase-1-scope.md) | ⚠️ Decorator sugar can obscure the unimplemented-tool guard | ✅ Possible but duplicates Python helpers |
+| Import-surface guard (`tests/test_mcp_server.py` asserts no `subprocess`, `os.system`, `os.popen`, no HTTP client in `scripts.mcp_server.prompts/tools`) | ✅ Trivial to enforce — one module set to audit | ⚠️ FastMCP pulls in extra deps that widen the audit surface | ❌ Would need a TS-side equivalent |
+| Reuse of existing project helpers (`scripts/skill_linter.py`, `scripts/chat_history.py`) | ✅ Direct in-process call | ✅ Same | ❌ Cross-runtime IPC or duplicated logic |
+| Pin / supply-chain footprint | One pin (`mcp==1.27.1`) + `PyYAML` | Adds FastMCP version coupling on top | Node toolchain (`npm`, `tsc`, `dist/`) |
+| Smoke-test path | `task mcp:setup && task mcp:run` (already shipped) | Would re-wrap the same SDK | Separate test runner |
+
+Evidence the decision is already realised in code:
+
+- [`scripts/mcp_server/server.py`](../../scripts/mcp_server/server.py) — uses
+  `mcp.server.Server`, `mcp.server.stdio.stdio_server`, `InitializationOptions`
+  directly (no FastMCP decorators).
+- [`scripts/mcp_server/__init__.py`](../../scripts/mcp_server/__init__.py) —
+  pins `__version__` and declares stability/contract pointer.
+- [`scripts/mcp_server/requirements.txt`](../../scripts/mcp_server/requirements.txt)
+  — `mcp==1.27.1`, no FastMCP, no Node tooling.
+- [`scripts/mcp_setup.sh`](../../scripts/mcp_setup.sh) — onboarding writes
+  the Claude Desktop config snippet against `python -m scripts.mcp_server`.
+
+## Tool surface (Phase 1 scoping)
+
+Locked separately by [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) Phase 4
+amendment. The current ALLOWLIST is exactly two tools, registered as a
+hardcoded module-level tuple in
+[`scripts/mcp_server/tools.py`](../../scripts/mcp_server/tools.py):
+
+| Tool | Mode | Source |
+|---|---|---|
+| `lint_skills` | read-only | wraps `scripts.skill_linter.lint_file` |
+| `chat_history_append` | path-scoped write | wraps `scripts.chat_history.append`; writes restricted to `agents/.agent-chat-history` or `.agent-chat-history` under the consumer root |
+
+No `push`, `merge`, `commit`, or prod-write surface is exposed. The
+unimplemented-tool envelope from
+[`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) governs the rest of
+the [`consumer_tool_catalog.json`](../../scripts/mcp_server/consumer_tool_catalog.json)
+entries.
+
+`agent-config init`, `agent-config skills list`, and
+`agent-config council estimate` (the speculative tool surface in the
+step-14 stub) are **not** exposed today. They stay terminal-gated because
+their natural shape is a stateful CLI. The AI Council (claude-sonnet-4-5 +
+gpt-4o, 2026-05-10, 2 rounds, $0.06) converged on a hardcoded module-level
+ALLOWLIST with mandatory path-scoping for any write tool, and locked the
+rule that engine-state-bearing operations stay off the MCP wire until a
+real consumer ask justifies amending the A0 boundary.
+
+## Install surface
+
+The step-14 stub speculated about an `agent-config install --mcp` flag.
+That shape was rejected in favour of two existing entrypoints, both
+already shipped:
+
+- **One-liner onboarding:** `task mcp:setup` runs
+  [`scripts/mcp_setup.sh`](../../scripts/mcp_setup.sh) — creates
+  `.venv-mcp/`, installs `mcp`, and prints the Claude Desktop JSON snippet
+  the operator pastes into
+  `~/Library/Application Support/Claude/claude_desktop_config.json`
+  (with the per-OS variants documented in
+  [`docs/mcp-server.md`](../mcp-server.md)).
+- **Config writer:** `./agent-config mcp:render --claude-desktop` writes
+  the user-scope Claude Desktop config directly.
+
+Writing the global Claude Desktop config from the npx dispatcher without
+an operator pasting JSON is **not** part of this contract — Claude Desktop
+restarts and config-merge semantics make silent rewrites a footgun. The
+copy-paste path stays the canonical install shape until non-dev recruit
+evidence under `agents/eval-findings/` demonstrates the manual step is the
+actual adoption blocker.
+
+## Consequences
+
+- Adding a third tool to the MCP server is a code-review event against
+  `ALLOWLIST` in `scripts/mcp_server/tools.py`. No settings flag, no env
+  var, no dynamic registration — see
+  [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) Phase 4 amendment.
+- Picking up a future protocol break (MCP SDK 2.x) is one pin bump in
+  `scripts/mcp_server/requirements.txt`, gated on the 12 import-surface +
+  behaviour tests in `tests/test_mcp_server.py` staying green.
+- Re-opening FastMCP or the TypeScript SDK requires a new ADR that
+  supersedes this one with evidence (Python SDK shipping a deprecation
+  or FastMCP closing the safety-audit gap on `tools/*`).
+
+## See also
+
+- [`mcp-phase-1-scope.md`](mcp-phase-1-scope.md) — Phase 1–6 hard contract.
+- [`mcp-cloud-scope.md`](mcp-cloud-scope.md) — hosted Worker bridge scope.
+- [`mcp-tool-stub-envelope.md`](mcp-tool-stub-envelope.md) — unimplemented-tool wire shape.

package/docs/contracts/adr-user-types-axis.md

@@ -0,0 +1,127 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# ADR — Runtime user-types axis (review lens, parallel to personas)
+
+> **Status:** Decided · 2026-05-15
+> **Source:** user-authored brief (no council session — direct user spec)
+> **Sibling axis (distinct layer):** [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — install-time `personal.user_type` filter; same vocabulary, different layer
+
+## Context
+
+The persona axis (`personas/`) was overloaded with two semantics:
+
+1. **Methodology lenses** — `qa`, `senior-engineer`, `critical-challenger`,
+   `developer`, `product-owner`. These voices answer: *how* we review.
+2. **End-user simulations** — proposals like `galabau-field-crew`,
+   `truck-driver`, `metalworking-shop`. These voices answer: *who*
+   experiences the software.
+
+Mixing the two collapses the taxonomy. A `qa` reviewer applies QA
+methodology regardless of which end-user the software serves. A
+`galabau-field-crew` is not a review methodology — it is the end-user
+viewpoint a methodology reviewer should adopt while reviewing.
+
+The composition the system needs is orthogonal:
+
+```
+/refine-ticket --personas=qa --user-type=truck-driver PROJ-123
+```
+
+QA methodology applied through a truck-driver end-user lens. Two
+axes, one orthogonal product.
+
+## Decision
+
+Split into a parallel axis. Add `.agent-src.uncompressed/user-types/`
+as a first-class directory mirroring the persona pipeline:
+
+- Source dir: `.agent-src.uncompressed/user-types/`
+- Schema doc: [`user-type-schema`](user-type-schema.md) — 7-section spine, ≤ 120 lines
+- JSON schema: [`scripts/schemas/user-type.schema.json`](../../scripts/schemas/user-type.schema.json)
+- Linter: `scripts/skill_linter.py § lint_usertype`
+- CLI surface: `/refine-ticket --user-type=<id>` (single id in v1)
+- Composition: `--user-type=` and `--personas=` compose orthogonally
+
+Persona surface is **byte-identical** after this work. No persona
+moves, no schema change to `persona-schema.md` or `persona.schema.json`,
+no behaviour change to `--personas=`. The three seed user-types
+(`galabau-field-crew`, `metalworking-shop`, `truck-driver`) are born
+as user-types — existing personas stay as personas.
+
+## Consequences
+
+**Additive surface:**
+
+- One new CLI flag (`--user-type=`)
+- One new schema doc + JSON schema
+- One new linter hook (`lint_usertype` + classifier branch)
+- One new directory (`user-types/`) projected the same way `personas/`
+  is
+- Three seed files at merge time; consumer projects add their own
+  domain-specific user-types under `.agent-src/user-types/`
+
+**Locked v1 boundaries:**
+
+- CLI-only. Skills do NOT declare a default `user-types:` frontmatter
+  key in v1. Migration path to v2: if usage patterns show > 3 skills
+  citing the same user-type default, add the key and the audit script
+  to mirror `recommended_for_user_types` discipline (smaller surface
+  now, additive later).
+- Single user-type per invocation (`--user-type=<id>`, not a list).
+  Multi-user-type composition deferred to v2 with a one-line note —
+  it requires synthesis logic that does not exist yet and would block
+  v1 on a non-load-bearing nice-to-have.
+- **Review lens only.** User-types never provide trade execution
+  instructions. Guardrails encoded in every file's `Anti-Patterns`
+  section per [`user-type-schema § 5`](user-type-schema.md#-5--guardrails-encoded-in-every-anti-patterns-block).
+- **Anti-Generic Quality Bar.** Every user-type encodes ≥ 5 concrete,
+  domain-specific review points and ≥ 3 Unique Questions no other
+  persona asks verbatim. Generic prose is rejected at lint or review
+  time.
+
+## Alternatives considered
+
+**Alt-1 — Extend persona schema with a `subtype: end-user` discriminator.**
+Rejected. Same physical file, two semantics, two enforcement paths
+inside one linter hook. Scales worse: every persona-consuming surface
+(`--personas=`, `lint_persona`, `audit_persona_coverage.py`) would
+need a branch on `subtype` to know whether the artefact is a
+methodology lens or an end-user lens. The clean axis split is a
+single fork-point at the classifier; the subtype fork-point recurs at
+every consumption site.
+
+**Alt-2 — Reuse the existing `user-types/` (install-time) directory
+for runtime lenses.** Rejected. The install-time axis stores YAML
+configs filtering *which skills load*; the runtime axis stores
+Markdown lenses filtering *whose viewpoint a review adopts*. Same
+vocabulary, completely different content shape (YAML key-value vs.
+Markdown prose + frontmatter), completely different consumer
+(`scripts/install.sh` vs. `refine-ticket`). Co-locating them would
+force a single `kind:` discriminator on a directory whose two halves
+do not share a schema. The separation is in different physical paths
+(`user-types/` root vs. `.agent-src.uncompressed/user-types/`) and
+the vocabulary overlap is deliberate per [`adr-install-user-type-axis`](adr-install-user-type-axis.md).
+
+**Alt-3 — Defer the axis until end-user lenses prove themselves in
+the field.** Rejected. The methodology / end-user overload is already
+producing taxonomy drift in the persona README (review-lens vs
+end-user examples mixing). Splitting now is cheaper than splitting
+after three more end-user "personas" land.
+
+## Migration
+
+No migration. v1 ships with three seed user-types born under the new
+axis. Existing personas (`qa`, `developer`, `senior-engineer`,
+`product-owner`, `stakeholder`, `critical-challenger`, `ai-agent`,
+plus specialists) stay put. The `personas/README.md` gains one
+cross-link sentence pointing readers at the parallel axis when their
+intent is end-user simulation rather than methodology review.
+
+## See also
+
+- [`user-type-schema`](user-type-schema.md) — locked shape, 7-section spine, size budget, quality bar
+- [`persona-schema`](persona-schema.md) — sister axis (untouched by this ADR)
+- [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — install-time `personal.user_type` filter (distinct layer)

package/docs/contracts/user-type-schema.md

@@ -0,0 +1,146 @@
+---
+stability: beta
+keep-beta-until: 2026-08-14
+---
+
+# User-type Schema — runtime review-lens axis
+
+> **Status:** active · **Stability:** beta · **Owner:** step-6-user-types-axis
+> · **Linter:** `scripts/skill_linter.py § lint_usertype`
+> · **Source-of-truth dir:** `.agent-src.uncompressed/user-types/`
+> · **Sibling axis (distinct):** install-time `user-types/` (package root) — see [`adr-install-user-type-axis`](adr-install-user-type-axis.md)
+> · **ADR:** [`adr-user-types-axis`](adr-user-types-axis.md)
+
+Locks the canonical user-type shape. A user-type is a **runtime review
+lens** simulating a real end-user of the software under review (a
+galabau field crew, a metalworking shop, a truck driver). It is the
+twin of `personas/` along a different axis: persona = *how* we review
+(methodology — qa, senior-engineer); user-type = *who* we simulate
+(end-user — domain workflow + operational reality).
+
+## § 1 — Frontmatter
+
+| Key | Type | Required | Notes |
+|---|---|---|---|
+| `id` | string | yes | lowercase-hyphenated, must match filename stem |
+| `kind` | const `user-type` | yes | discriminator — locks this file as a review-lens user-type, separates it from the install-time user-type-axis YAMLs |
+| `description` | string | yes | one sentence, ≤ 160 chars (linter cap matches persona) |
+| `version` | string | yes | semver; bump on breaking changes |
+| `source` | enum | yes | `package` \| `project` — project-specific is the typical case (consumer-domain end-users) |
+
+`user-types:` is NOT a skill-frontmatter key in v1. The axis is
+CLI-only (`/refine-ticket --user-type=<id>`). Skill-level defaults are
+deferred to v2 — see [`adr-user-types-axis`](adr-user-types-axis.md).
+
+## § 2 — Required section spine (locked)
+
+User-types share the spine across the axis — no Core/Specialist split,
+no tier enum. Every user-type carries all seven sections:
+
+1. **Focus** — one paragraph. Who this lens is, the operational
+   context they work in, and what no other lens catches. End with one
+   sentence pinning the boundary: review-lens only, never operational
+   instruction source.
+2. **Daily Workflow** — concrete day-shape, not generic prose. What
+   they do at 06:00, 10:00, 15:00; what they look at, what they touch,
+   what they wait for.
+3. **Vocabulary** — domain terms the software must use (or must NOT
+   substitute). Bilingual where the trade is bilingual. Plain-language
+   over engineer-language where the user is non-technical.
+4. **Operational Constraints** — mobile / offline / gloves / noise /
+   PPE / time pressure / connectivity / lighting / dead-zones /
+   hours-of-service / break-windows / shop-floor vs office split.
+   Each constraint is a UI / flow signal, not generic empathy.
+5. **Unique Questions** — ≥ 3 questions no persona asks verbatim.
+   Each must be falsifiable against the ticket under review. (Linter
+   warns < 3, matches persona heuristic.)
+6. **Ticket Red Flags** — what this lens would flag as missing or
+   unrealistic when reviewing a ticket. Bullet list, each item names a
+   concrete signal a generic reviewer would miss.
+7. **Anti-Patterns** — what this lens must refuse to do. Guardrails
+   are non-negotiable here: **review-only, never operational
+   instruction**. No trade execution (welding procedure, electrical
+   work, structural advice). No dangerous how-to. No medical / legal
+   / engineering advice. Generic prose ("consider usability") is
+   itself an anti-pattern.
+
+`Composes well with` is permitted as an optional eighth section
+(advisory pairings with personas), not budget-counted.
+
+## § 3 — Size budget
+
+| Section count | Line cap | Rationale |
+|---|---|---|
+| 7 | ≤ 120 | Matches the persona core budget. Spine is wider than a
+core persona (7 vs 5 sections) but narrower than a wing-3/4 specialist
+(no Critical Rules + Workflows blocks). 120 is the larger of the two
+candidate caps and the persona core uses it for a 5-section spine —
+the extra two sections need the headroom. |
+
+Enforced by `lint-skills` against the full file including frontmatter
+and trailing blank line.
+
+## § 4 — Anti-Generic Quality Bar (merge gate)
+
+Every user-type must encode **≥ 5 concrete, domain-specific review
+points** across `Daily Workflow`, `Vocabulary`, `Operational
+Constraints`, and `Ticket Red Flags`. Generic prose is REJECTED at
+lint or review time:
+
+- ❌ "consider mobile usability"  →  ✅ "capacitive touch fails with
+  wet leather gloves at 4 °C; tap targets ≥ 60 px or voice command"
+- ❌ "think about offline"  →  ✅ "no signal in cellar yards; queue
+  changes locally, conflict-resolve on the morning brief"
+- ❌ "users want reports"  →  ✅ "end-of-day proof = timestamped photo
+  + customer signature + GPS fix; anything less is a billing dispute"
+
+The Reviewer test: a generic reviewer persona could not have produced
+the `Unique Questions` or `Ticket Red Flags` of this file. If they
+could, the file is generic.
+
+## § 5 — Guardrails (encoded in every Anti-Patterns block)
+
+User-types are review lenses, not operational manuals. Every file's
+`## Anti-Patterns` section MUST explicitly forbid:
+
+- Trade-execution instructions (welding procedure, electrical work,
+  structural advice, anything that could harm if followed)
+- Dangerous how-to (chemical handling, equipment operation, work-at-
+  height procedures)
+- Medical / legal / engineering advice that requires a licensed
+  practitioner
+
+Allowed and encouraged: workflow realism, ticket gap analysis,
+terminology correction, mobile / offline / safety / approval signals
+as ticket-requirement signals.
+
+## § 6 — Schema enforcement
+
+The linter (`scripts/skill_linter.py § lint_usertype`) enforces:
+
+- frontmatter shape (table in § 1)
+- `kind` const value
+- required sections per § 2
+- size budget per § 3
+- ≥ 3 bullets in `Unique Questions`
+- `id` matches filename stem
+- description ≤ 160 chars
+
+Authors must use the template at
+`.agent-src.uncompressed/user-types/_template/user-type.md`.
+
+## § 7 — Versioning
+
+Section rename / add / remove → ADR + linter update + user-type
+migrations in the same PR. Size-cap tightening is breaking when it
+forces existing user-types to lose content; size-cap loosening is
+non-breaking. The `kind` const is locked — renaming requires a major
+version bump and a separate ADR.
+
+## See also
+
+- [`persona-schema`](persona-schema.md) — sister axis (methodology vs end-user)
+- [`adr-user-types-axis`](adr-user-types-axis.md) — why the axis split exists
+- [`adr-install-user-type-axis`](adr-install-user-type-axis.md) — the install-time `user_type` axis (distinct layer, same vocabulary)
+- `.agent-src.uncompressed/user-types/README.md` — authoring entry point
+- `.agent-src.uncompressed/user-types/_template/user-type.md` — template starter

package/docs/recruits/_template.md

@@ -0,0 +1,81 @@
+# Recruit — `<short-handle>`
+
+> **step-13 Phase 1 intake template.** One file per recruit. Filename:
+> `<YYYY-MM-DD>-<source>-<handle>.md` (e.g. `2026-05-20-indiehackers-jsmith.md`).
+> The maintainer fills this in **before** the recruit's first session; the
+> session-log section gets appended live during the walkthrough.
+
+## Identity & source
+
+- **Handle / display name:** `<as-they-want-to-be-credited>`
+- **Source channel:** (indie-hackers | r/ContentWritingJobs | product-hunt | direct-dm | other)
+- **First contact:** YYYY-MM-DD via `<thread-url-or-DM-context>`
+- **Role / self-description:** `<one-line, in their words>`
+- **User-type fit:** (consultant | creator | founder | finance | ops | gtm | other)
+- **Tool host they already use:** (claude-desktop | claude-code | cursor | windsurf | copilot | chatgpt-web | none)
+
+## Consent
+
+- **Attribution:** (full-name-OK | first-name-OK | role-only | fully-anonymous)
+- **Screenshot publication:** (yes | yes-with-redaction | no)
+- **Verbatim quote publication:** (yes | yes-with-review | no)
+- **Case-study publication if outcome lands:** (yes | maybe-revisit | no)
+- **Consent record:** `<link-to-dm-or-email-thread-or-signed-form>`
+
+> Consent gate per step-13 Phase 1 row 3 — a recruit without an explicit
+> consent record cannot anchor `agents/eval-findings/`. Anonymised
+> finding is acceptable; missing consent record is not.
+
+## Pre-session readiness
+
+- [ ] Recruit has Claude Desktop installed *(or equivalent MCP host)*
+- [ ] Recruit has a real task ready to bring to the session
+- [ ] Maintainer has [`docs/mcp-server.md`](../mcp-server.md) open in another tab
+- [ ] Maintainer has stopwatch / screen-recording ready for the install-time
+  measurement (Phase 1 row 2 — `< 10 minutes` gate)
+
+## Session log
+
+Append-only during the walkthrough. Timestamp every observation;
+"silent" minutes are also a signal.
+
+```
+HH:MM  start — recruit shares screen, opens Claude Desktop
+HH:MM  install step 1 (`task mcp:setup`): outcome / friction / quote
+HH:MM  install step 2 (Claude Desktop config paste): outcome / friction / quote
+HH:MM  first invocation attempt: prompt / which skill fired / verdict
+...
+HH:MM  end — total install time: __ min __ s
+```
+
+## Friction inventory
+
+At least **two** real friction points (per step-12 Phase 7 L130 spirit).
+Empty list = the session wasn't real.
+
+1. <where they stalled, in their words> → <what we fixed / parked>
+2. <...>
+
+## Outcome verdict
+
+- **MCP setup time:** `__ minutes __ seconds` (gate: `< 10 min`)
+- **First useful invocation reached without terminal?:** (yes | no | partial)
+- **Recruit would recommend to a peer?:** (yes | maybe | no | declined-to-answer)
+- **Eligible to anchor `agents/eval-findings/`?:** (yes | no — reason)
+
+## Cross-links
+
+- **Eval-finding file (if logged):** `agents/eval-findings/YYYY-MM-DD-<slug>.md`
+- **Case-study file (if subject opted in):** `docs/case-studies/YYYY-MM-DD-<type>-<slug>.md`
+- **Roadmap rows closed by this session:**
+  - step-13 P1 row 1 (recruit) — yes / no
+  - step-13 P1 row 2 (`< 10 min` gate) — yes / no
+  - step-13 P1 row 3 (consent record) — yes / no
+
+## Maintainer follow-up
+
+- [ ] Eval-finding committed
+- [ ] Recruit thanked + sent the published finding link
+- [ ] Skill-description deltas filed *(any friction that maps to a
+  skill description widening or a missing trigger phrase)*
+- [ ] Case-study slot offered *(if outcome was useful + consent allows)*

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.18.0",
+    "version": "2.19.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/compress.py

@@ -346,6 +346,7 @@ TOOL_DIRS = {
 SKILLS_SOURCE = PROJECT_ROOT / ".agent-src" / "skills"
 COMMANDS_SOURCE = PROJECT_ROOT / ".agent-src" / "commands"
 PERSONAS_SOURCE = PROJECT_ROOT / ".agent-src" / "personas"
+USER_TYPES_SOURCE = PROJECT_ROOT / ".agent-src" / "user-types"
 CLAUDE_SKILLS_DIR = PROJECT_ROOT / ".claude" / "skills"
 
 PERSONA_TOOL_DIRS = {
@@ -353,6 +354,11 @@ PERSONA_TOOL_DIRS = {
     ".cursor/personas": "../../.agent-src/personas",
 }
 
+USER_TYPE_TOOL_DIRS = {
+    ".claude/user-types": "../../.agent-src/user-types",
+    ".cursor/user-types": "../../.agent-src/user-types",
+}
+
 # Map tool-projection directories to the canonical tool ID used by
 # `.agent-tools.yml`. Directories not in this map are always emitted.
 _DIR_TOOL_ID = {
@@ -361,6 +367,8 @@ _DIR_TOOL_ID = {
     ".clinerules": "cline",
     ".claude/personas": "claude-code",
     ".cursor/personas": "cursor",
+    ".claude/user-types": "claude-code",
+    ".cursor/user-types": "cursor",
 }
 
 
@@ -901,6 +909,43 @@ def generate_persona_symlinks() -> int:
     return total
 
 
+def generate_user_type_symlinks() -> int:
+    """Create symlink directories for user-types (.claude/user-types/, .cursor/user-types/).
+
+    Symlinks each user-type .md file from .agent-src/user-types/ into tool-specific
+    directories. Excludes README.md and _template/ — those are authoring scaffolding,
+    not user-type lenses.
+    """
+    if not USER_TYPES_SOURCE.exists():
+        print("  ⚠️  .agent-src/user-types/ not found — skipping user-types")
+        return 0
+
+    user_types = sorted([
+        f.name for f in USER_TYPES_SOURCE.glob("*.md") if f.stem != "README"
+    ])
+    tool_dirs = _filter_tool_dirs(USER_TYPE_TOOL_DIRS)
+    total = 0
+    for tool_dir, rel_prefix in tool_dirs.items():
+        target_dir = PROJECT_ROOT / tool_dir
+        target_dir.mkdir(parents=True, exist_ok=True)
+
+        # Clean stale symlinks
+        for item in target_dir.iterdir():
+            if item.is_symlink() and item.name not in user_types and item.name != "README.md":
+                item.unlink()
+
+        for user_type in user_types:
+            link = target_dir / user_type
+            target = Path(rel_prefix) / user_type
+            if link.exists() or link.is_symlink():
+                link.unlink()
+            link.symlink_to(target)
+            total += 1
+
+    info(f"  ✅  Created {total} user-type symlinks across {len(tool_dirs)} tool directories ({len(user_types)} user-types each)")
+    return total
+
+
 def generate_tools() -> None:
     """Generate all tool-specific directories and files.
 
@@ -916,13 +961,14 @@ def generate_tools() -> None:
     skills = generate_claude_skills() if _tool_active("claude-code") else 0
     commands = generate_claude_commands() if _tool_active("claude-code") else 0
     personas = generate_persona_symlinks()
+    user_types = generate_user_type_symlinks()
     cursor_mdc = generate_cursor_mdc_rules() if _tool_active("cursor") else 0
     windsurf_modern = generate_windsurf_modern_rules() if _tool_active("windsurf") else 0
     cursor_cmds = generate_cursor_commands() if _tool_active("cursor") else 0
     windsurf_wf = generate_windsurf_workflows() if _tool_active("windsurf") else 0
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas} "
+        f"commands={commands} personas={personas} user_types={user_types} "
         f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
         f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf} "
         f"windsurfrules={windsurfrules}"
@@ -943,7 +989,7 @@ def generate_tools() -> None:
 # them to symlinks (everything else is always symlinked).
 
 # Subdirectories of .agent-src/ that map into .augment/ as symlinks.
-AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "templates", "contexts", "scripts")
+AUGMENT_SYMLINK_DIRS = ("skills", "commands", "guidelines", "personas", "user-types", "templates", "contexts", "scripts")
 # Top-level files to symlink into .augment/ (README, etc.)
 AUGMENT_SYMLINK_FILES = ("README.md",)
 

package/scripts/schemas/user-type.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/user-type.schema.json",
+  "title": "User-type frontmatter",
+  "$comment": "Source: docs/contracts/user-type-schema.md. The runtime review-lens axis seeded under .agent-src.uncompressed/user-types/. Distinct from the install-time user-type-axis YAMLs in user-types/ (root) which carry their own user-type-axis.schema.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "kind", "description", "version", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Must match the user-type filename stem."
+    },
+    "kind": {
+      "type": "string",
+      "const": "user-type",
+      "description": "Discriminator — locks this file as a review-lens user-type, distinct from the install-time user-type-axis YAMLs."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"],
+      "description": "Project-specific the typical case — most end-user simulations are consumer-domain, not package-defaults."
+    }
+  }
+}