@event4u/agent-config 2.17.0 → 2.18.0

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.16.0"
+agent_config_version: "2.17.0"
 
 # --- Project identity ---
 project:

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "2.17.0",
+    "version": "2.18.0",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -702,6 +702,35 @@ our recommendation order, not its support status.
 > that forces a new era split (`# Era: 2.16.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.18.0](https://github.com/event4u-app/agent-config/compare/2.17.0...2.18.0) (2026-05-16)
+
+### Features
+
+* **lint:** user-type axis frontmatter audit + task wiring ([322bf1d](https://github.com/event4u-app/agent-config/commit/322bf1dc805550cb8c234808bde4235aaf0ba39e))
+* **mcp:** filter skill prompts by personal.user_type ([0b09911](https://github.com/event4u-app/agent-config/commit/0b09911ea6ed2870b12b52ee67a922c3df1f919c))
+* **install:** wire --user-type flag across install entrypoints ([6589c6b](https://github.com/event4u-app/agent-config/commit/6589c6bce4682d521c12727adc4903e7333a421d))
+* **install:** add user_type schema + template placeholder + ADR ([3ede84d](https://github.com/event4u-app/agent-config/commit/3ede84d79ce0d3612ae6d2a862ae239cb01f8762))
+
+### Documentation
+
+* **roadmaps:** close step-9 user-types axis + flip parent step-12 ([f1926dc](https://github.com/event4u-app/agent-config/commit/f1926dc6905128bfcb909dc03e47a37c7754e4e3))
+
+### Tests
+
+* **install:** cover --user-type + sync user_type preservation ([349478f](https://github.com/event4u-app/agent-config/commit/349478fccc608a2a9818585f7c2a43368ee076c0))
+
+### Chores
+
+* **docs:** drop broken step-12 link from getting-started-by-role ([351505a](https://github.com/event4u-app/agent-config/commit/351505a8fbc6626db5dd26cea494d2a4dbaead89))
+* **contracts:** inline council verdict + pragma roadmap source-trails ([4442030](https://github.com/event4u-app/agent-config/commit/4442030543b02511ced3643d9c6062e0722448d9))
+* **contracts:** drop transient roadmap refs from stable artifacts ([ecad21e](https://github.com/event4u-app/agent-config/commit/ecad21e16b7269257ba95d104b2dce06a9f140a5))
+* **contracts:** align keep-beta-until with 90-day window cap ([5c87588](https://github.com/event4u-app/agent-config/commit/5c8758854d19f5790b21bba41c4631e8460caa5e))
+* **roadmaps:** retag step-13/14 complexity to lightweight ([e87cd35](https://github.com/event4u-app/agent-config/commit/e87cd35483cb16eb39574a10318c2f9cb720e9a7))
+* **template:** bump agent_config_version pin to 2.17.0 ([f6bb24e](https://github.com/event4u-app/agent-config/commit/f6bb24e1267623bd49dffd1deb0c9ae071ea4906))
+* **index:** regenerate index after upstream privacy-review desc edit ([fd7fe24](https://github.com/event4u-app/agent-config/commit/fd7fe248b2297021912ec41aff5dd5b1596c9989))
+
+Tests: 4476 (+17 since 2.17.0)
+
 ## [2.17.0](https://github.com/event4u-app/agent-config/compare/2.16.0...2.17.0) (2026-05-15)
 
 ### Features

package/config/agent-settings.template.yml

@@ -73,6 +73,13 @@ personal:
   # See rules/autonomous-execution.md for the full definition.
   autonomy: auto
 
+  # Primary user-type for skill filtering (step-9 axis).
+  # Empty string ("") = no filter (legacy behavior — every skill surfaces).
+  # Set this via `bash scripts/install --user-type=<id>` or hand-edit later.
+  # Valid ids: consultant | creator | developer | finance | founder | gtm | ops
+  # See user-types/README.md for the per-id contract.
+  user_type: "__USER_TYPE__"
+
 # --- Project / team preferences ---
 project:
   # Path to the PR template file (relative to project root)

package/docs/catalog.md

@@ -148,7 +148,7 @@ are excluded.
 | skill | [`playwright-testing`](../.agent-src/skills/playwright-testing/SKILL.md) |  | Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns. |
 | skill | [`po-discovery`](../.agent-src/skills/po-discovery/SKILL.md) |  | Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'. |
 | skill | [`positioning-strategy`](../.agent-src/skills/positioning-strategy/SKILL.md) |  | Use when locking the market frame — category, segment, alternative, point-of-view — before messaging, launch, or pricing rides on it. Triggers on 'who are we for', 'opposable audit'. |
-| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows for GDPR / CCPA / HIPAA fit — regulatory-regime delta, consent shape, breach-impact triage. Triggers on 'is this GDPR-safe', 'do we need a DPA'. |
+| skill | [`privacy-review`](../.agent-src/skills/privacy-review/SKILL.md) |  | Use when reviewing data flows, support macros, refund templates for GDPR/CCPA/HIPAA fit — regime, consent, PII redaction (email, order-id), breach triage. Triggers 'is this GDPR-safe', 'PII redact'. |
 | skill | [`project-analysis-core`](../.agent-src/skills/project-analysis-core/SKILL.md) |  | Raw discovery primitives — project discovery, version resolution, docs loading, architecture mapping, execution flow. Called by `universal-project-analysis`. Single-pass scan → `project-analyzer`. |
 | skill | [`project-analysis-hypothesis-driven`](../.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md) |  | Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'. |
 | skill | [`project-analysis-laravel`](../.agent-src/skills/project-analysis-laravel/SKILL.md) |  | Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns. |

package/docs/contracts/adr-install-user-type-axis.md

@@ -0,0 +1,107 @@
+---
+stability: beta
+keep-beta-until: 2026-08-13
+---
+
+# ADR — Install-time user-type axis
+
+> **Status:** Decided · 2026-05-15
+> **Source:** AI Council session 2026-05-15-step12-closure-run2 (Reviewer-A, Reviewer-B, Reviewer-C) D1 verdict — ACCEPT with amendments: seed all 7 user-types, cap roadmap at ≤5 phases, cap deliverables per phase.
+> **Sibling axis (distinct layer):** the runtime `personas/` ladder. The
+> install-time `user_type` axis filters *which skills load*; personas filter
+> *which voice reviews*. The two compose orthogonally.
+
+## Decision
+
+Install-time skill filtering uses a dedicated axis seeded under
+`user-types/` (package root, not `.agent-src.uncompressed/`). The
+selection lands in the consumer's `.agent-settings.yml` under
+`personal.user_type: <id>` via `agent-config install --user-type=<id>`.
+Runtime skill discovery intersects each skill's
+`recommended_for_user_types` frontmatter against
+`personal.user_type`; unset → "show all skills" (legacy behavior).
+
+The `user-types/` directory holds **seven** YAML configs — `consultant`,
+`creator`, `developer`, `finance`, `founder`, `gtm`, `ops` — matching
+every value already in active use across 32 skills' frontmatter. Adding
+an eighth value requires a new YAML plus a frontmatter audit (Phase 4).
+Schema: [`scripts/schemas/user-type-axis.schema.json`](../../scripts/schemas/user-type-axis.schema.json).
+
+## Why this is distinct from the review-lens axis
+
+Same vocabulary, different layer:
+
+| Axis | Layer | Owner roadmap | Where it bites |
+|---|---|---|---|
+| **Install filter** (this ADR) | onboarding / `.agent-settings.yml` | `step-9-user-types-axis.md` | Which skills surface first at discovery |
+| **Review lens** | runtime / `refine-ticket` | `step-6-user-types-axis.md` | Whose viewpoint a review adopts |
+
+The two never collide because they live in different files and
+different config keys. Install filter narrows *which skills load by
+default*; review lens narrows *whose voice a refine-ticket review
+adopts*. Authors can use both, neither, or one — independently.
+
+The naming overlap is preserved deliberately. Consumers think in terms
+of "I am a consultant" once; both axes consume that fact in their own
+layer. Renaming one would force consumers to learn a second vocabulary
+for the same self-identification.
+
+## Why install-time and not runtime-only
+
+Three options were considered:
+
+1. **Runtime-only filter** — read `personal.user_type` on every
+   session start, no install-time wiring. Rejected: needs the value
+   to exist before any skill loads; bootstrapping into an empty
+   `.agent-settings.yml` is fragile and undocumented.
+2. **Install-time flag, no runtime filter** — `--user-type` writes the
+   key, but skill discovery ignores it. Rejected: the value is dead
+   metadata without the discovery hook (Phase 3). Already the state of
+   the codebase before this roadmap; the whole point of step-9 is to
+   wire it.
+3. **Install-time flag + runtime filter** *(chosen)* — `--user-type`
+   writes the key; the discovery hook intersects frontmatter against
+   it. Legacy "no flag" path is preserved by treating an unset value
+   as "match all". Additive, opt-in, no breaking change.
+
+## Consequences
+
+- `scripts/install.sh`, `scripts/install.py`, `scripts/install` each
+  accept `--user-type=<id>`. Validation against `user-types/*.yml`
+  stems happens in one place (`install.py`) and the bash entry-point
+  delegates. Invalid values fail fast with a non-zero exit.
+- `config/agent-settings.template.yml` keeps a commented
+  `personal.user_type:` stub documenting the seven valid values.
+- The existing `--interactive` flag (legacy `.agent-config.local.json`
+  stub) is preserved for backward compat; the new flag is the
+  first-class path going forward. A future ADR can deprecate the JSON
+  stub once consumers migrate.
+- Frontmatter audit (Phase 4) catches drift: every value used in
+  `recommended_for_user_types` MUST have a corresponding YAML, and
+  every YAML SHOULD be consumed by at least one skill. The audit ships
+  as a CI gate (`task lint-user-type-axis` →
+  [`scripts/audit_user_type_axis.py`](../../scripts/audit_user_type_axis.py)).
+  Initial sweep at Phase 4 close: 7 declared / 7 used / 0 orphans / 0
+  unused — coverage is clean, no rename or backfill needed. Report:
+  [`agents/reports/user-type-axis-audit.md`](../../agents/reports/user-type-axis-audit.md).
+- Adding an 8th value is non-trivial by design — it requires a YAML, a
+  schema-compatible frontmatter rollout, and a roadmap entry. The
+  friction is the feature: a sprawling axis defeats the purpose of
+  filtering.
+
+## Open questions deferred
+
+- Skill-loader hook location is left to Phase 3 — likely
+  `scripts/skill_linter.py`'s discovery pass plus a runtime helper for
+  agent hosts that read the axis directly.
+- Whether to surface a "show outside `<id>` filter" affordance in
+  agent hosts is left to host-side UX, not enforced by this ADR.
+- The `default_skill_priority` field is informational in v1 (no
+  loader consumes it yet). Phase 3 may promote it to a sort key.
+
+## See also
+
+- [`user-types/README.md`](../../user-types/README.md) — schema + seed table
+- [`docs/contracts/universal-skills.md`](universal-skills.md) — always-loaded floor
+- [`docs/contracts/rule-router.md`](rule-router.md) — kernel + router
+  architecture (sibling but orthogonal axis)

package/docs/contracts/init-telemetry.md

@@ -1,11 +1,11 @@
 ---
 stability: beta
-keep-beta-until: 2026-08-15
+keep-beta-until: 2026-08-13
 ---
 
 # Init Telemetry v1
 
-> **Status:** beta · **Owner:** step-12 Phase 7 (`agents/roadmaps/step-12-universal-os-reframe.md`) · **Depends on:** [`step-9-user-types-axis`](../../agents/roadmaps/step-99-north-star-restructure.md) telemetry wire-up · **Stability:** additive only
+> **Status:** beta · **Depends on:** install-time `user_type` axis telemetry wire-up · **Stability:** additive only
 
 ## Purpose
 
@@ -123,7 +123,6 @@ When `telemetry.init: false`, the producer:
 
 ## Cross-references
 
-- [`step-12-universal-os-reframe.md`](../../agents/roadmaps/step-12-universal-os-reframe.md) Phase 7 L127 — the box this contract pre-authors.
 - [`universal-skills.md`](universal-skills.md) — sibling contract for the allowlist this telemetry validates against.
 - [`router-blending.md`](router-blending.md) — the user-type → skill blend that telemetry confirms is being used.
 - [`STABILITY.md`](STABILITY.md) — schema_version bump rules.

package/docs/getting-started-by-role.md

@@ -4,7 +4,7 @@
 
 `agent-config` ships ~210 skills, ~67 rules, and ~124 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
-> **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates. See [`agents/roadmaps/step-12-universal-os-reframe.md`](../agents/roadmaps/step-12-universal-os-reframe.md).
+> **Eval-gated messaging note.** Until `task bench --corpus non-dev` reports `selection_accuracy >= 0.60` (step-12 Phase 1 exit), this page is documentation, not marketing. The skills listed below are the candidates the corpus tests against; their description quality is what the eval validates.
 
 ---
 

package/package.json

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

package/scripts/audit_user_type_axis.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Audit the user-type axis frontmatter coverage (step-9 Phase 4).
+
+Two checks across `.agent-src.uncompressed/skills/`:
+
+1. **Orphan values** — every `recommended_for_user_types` value must have
+   a corresponding `user-types/<value>.yml` config. Orphans are FATAL
+   (exit 1) — they imply the runtime filter would tag prompts against a
+   user-type with no documented identity.
+2. **Unused configs** — every `user-types/*.yml` should be consumed by
+   at least one skill. Unused configs are WARN-only (exit 0): seeding
+   future identities ahead of consumption is allowed.
+
+Writes a markdown report to `agents/reports/user-type-axis-audit.md` and
+emits a one-line summary to stdout. Stdlib-only — no PyYAML dependency.
+
+Usage:
+    python3 scripts/audit_user_type_axis.py            # human report + exit code
+    python3 scripts/audit_user_type_axis.py --quiet    # exit code only
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections import defaultdict
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_ROOT = REPO_ROOT / ".agent-src.uncompressed" / "skills"
+USER_TYPES_ROOT = REPO_ROOT / "user-types"
+REPORT_PATH = REPO_ROOT / "agents" / "reports" / "user-type-axis-audit.md"
+
+_FRONTMATTER_LINE = re.compile(
+    r"^recommended_for_user_types:\s*\[([^\]]*)\]\s*$",
+    re.MULTILINE,
+)
+
+
+def _declared_user_types() -> set[str]:
+    """Read `user-types/*.yml` stems (one identity per YAML file)."""
+    if not USER_TYPES_ROOT.is_dir():
+        return set()
+    return {p.stem for p in USER_TYPES_ROOT.glob("*.yml")}
+
+
+def _scan_skill_values() -> dict[str, list[Path]]:
+    """Map every frontmatter user-type value → list of declaring SKILL.md paths."""
+    by_value: dict[str, list[Path]] = defaultdict(list)
+    if not SKILLS_ROOT.is_dir():
+        return by_value
+    for skill_md in sorted(SKILLS_ROOT.rglob("SKILL.md")):
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+        # Frontmatter is the leading `---` block — strip everything after.
+        if text.startswith("---\n"):
+            end = text.find("\n---", 4)
+            fm = text[4:end] if end >= 0 else text
+        else:
+            fm = text[:4096]
+        match = _FRONTMATTER_LINE.search(fm)
+        if not match:
+            continue
+        for raw in match.group(1).split(","):
+            value = raw.strip().strip('"').strip("'")
+            if value:
+                by_value[value].append(skill_md.relative_to(REPO_ROOT))
+    return by_value
+
+
+def _render_report(
+    declared: set[str],
+    by_value: dict[str, list[Path]],
+    orphans: set[str],
+    unused: set[str],
+) -> str:
+    lines: list[str] = [
+        "# User-type axis — frontmatter coverage audit",
+        "",
+        "Generated by `scripts/audit_user_type_axis.py` (step-9 Phase 4).",
+        "",
+        f"- Declared user-types (`user-types/*.yml`): **{len(declared)}**",
+        f"- Distinct frontmatter values across skills: **{len(by_value)}**",
+        f"- Orphans (FATAL): **{len(orphans)}**",
+        f"- Unused configs (WARN): **{len(unused)}**",
+        "",
+        "## Coverage matrix",
+        "",
+        "| user-type | declared | consuming skills |",
+        "| --- | --- | --- |",
+    ]
+    for ut in sorted(declared | set(by_value)):
+        flag_declared = "yes" if ut in declared else "**no (orphan)**"
+        count = len(by_value.get(ut, []))
+        lines.append(f"| `{ut}` | {flag_declared} | {count} |")
+    if orphans:
+        lines.extend(["", "## Orphans", ""])
+        for orphan in sorted(orphans):
+            lines.append(f"- `{orphan}` — referenced by:")
+            for path in by_value[orphan]:
+                lines.append(f"  - `{path}`")
+    if unused:
+        lines.extend(["", "## Unused configs (WARN)", ""])
+        for stem in sorted(unused):
+            lines.append(f"- `user-types/{stem}.yml` has no consuming skill yet.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    quiet = "--quiet" in argv
+    declared = _declared_user_types()
+    by_value = _scan_skill_values()
+    used = set(by_value)
+    orphans = used - declared
+    unused = declared - used
+
+    report = _render_report(declared, by_value, orphans, unused)
+    REPORT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    REPORT_PATH.write_text(report, encoding="utf-8")
+
+    if not quiet:
+        sys.stdout.write(
+            f"user-type-axis audit — declared={len(declared)} "
+            f"used={len(used)} orphans={len(orphans)} unused={len(unused)}\n"
+        )
+        if orphans:
+            sys.stdout.write(
+                "  FAIL orphans: " + ", ".join(sorted(orphans)) + "\n"
+            )
+        if unused:
+            sys.stdout.write(
+                "  warn unused: " + ", ".join(sorted(unused)) + "\n"
+            )
+        sys.stdout.write(f"  report: {REPORT_PATH.relative_to(REPO_ROOT)}\n")
+
+    return 1 if orphans else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/install

@@ -15,6 +15,10 @@
 #   --source <dir>    Package source directory (default: auto-detect)
 #   --target <dir>    Target project root (default: cwd)
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --user-type <id>  Primary user-type for skill filtering (step-9 axis).
+#                     Valid ids: consultant | creator | developer | finance
+#                     | founder | gtm | ops. Default: empty (no filter).
+#                     Written to personal.user_type in .agent-settings.yml.
 #   --tools <list>    Comma-separated tool IDs to install (default: all).
 #                     Valid: claude-code,claude-desktop,cursor,windsurf,
 #                            cline,gemini-cli,copilot,augment,aider,codex,
@@ -82,12 +86,13 @@ SCOPE=""
 CUSTOM_PATH=""
 OFFLINE=false
 MINIMAL=false
+USER_TYPE=""
 
 # Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
 VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex roocode continue kilocode zed jetbrains kiro all"
 
 show_help() {
-    sed -n '3,54p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,58p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
 }
 
 list_tools() {
@@ -146,6 +151,8 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --user-type)     USER_TYPE="$2"; shift 2 ;;
+        --user-type=*)   USER_TYPE="${1#*=}"; shift ;;
         --tools)         TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
         --tools=*)       TOOLS="${TOOLS:+$TOOLS,}${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
         --ai)            TOOLS="${TOOLS:+$TOOLS,}$2"; TOOLS_EXPLICIT=true; shift 2 ;;
@@ -309,6 +316,7 @@ run_bridges() {
 
     local args=(--project "$TARGET_DIR" --package "$SOURCE_DIR")
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
+    [[ -n "$USER_TYPE" ]] && args+=(--user-type="$USER_TYPE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
     $GLOBAL && args+=(--global)

package/scripts/install.py

@@ -45,6 +45,8 @@ except ImportError:  # pragma: no cover — alt sys.path layout
 DEFAULT_PROFILE = "balanced"
 SUPPORTED_PROFILES = ("minimal", "balanced", "full")
 COST_PROFILE_PLACEHOLDER = "__COST_PROFILE__"
+USER_TYPE_PLACEHOLDER = "__USER_TYPE__"
+USER_TYPES_DIR = "user-types"
 
 # Env-var equivalent of --force for CI / scripted installs (P3.4).
 # When set to "1" the install run treats every conflict as
@@ -781,7 +783,44 @@ def _render_template(template: str, profile_values: "dict[str, str]") -> str:
     return body
 
 
-def ensure_agent_settings(project_root: Path, package_root: Path, profile: str, force: bool) -> None:
+def _load_valid_user_types(package_root: Path) -> list[str]:
+    """Return the sorted user-type slugs shipped under ``user-types/``.
+
+    Maps `user-types/<id>.yml` → `<id>`. The ``README.md`` is skipped.
+    Empty list when the directory is absent (older package payloads).
+    """
+    directory = package_root / USER_TYPES_DIR
+    if not directory.is_dir():
+        return []
+    return sorted(p.stem for p in directory.glob("*.yml"))
+
+
+def _validate_user_type(package_root: Path, value: str) -> str:
+    """Return the validated user-type slug (empty string allowed → no filter)."""
+    cleaned = (value or "").strip()
+    if not cleaned:
+        return ""
+    valid = _load_valid_user_types(package_root)
+    if not valid:
+        fail(
+            f"--user-type={cleaned} requested but no user-types/*.yml present "
+            f"under {package_root}"
+        )
+    if cleaned not in valid:
+        fail(
+            f"Unknown --user-type={cleaned}. Valid: {', '.join(valid)} "
+            "(empty string disables the filter)."
+        )
+    return cleaned
+
+
+def ensure_agent_settings(
+    project_root: Path,
+    package_root: Path,
+    profile: str,
+    force: bool,
+    user_type: str = "",
+) -> None:
     target = project_root / SETTINGS_FILE
     profile_source = package_root / "config" / "profiles" / f"{profile}.ini"
     template_source = package_root / "config" / "agent-settings.template.yml"
@@ -794,12 +833,16 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
     template = template_source.read_text(encoding="utf-8")
     if COST_PROFILE_PLACEHOLDER not in template:
         fail(f"Template is missing placeholder {COST_PROFILE_PLACEHOLDER}")
+    if USER_TYPE_PLACEHOLDER not in template:
+        fail(f"Template is missing placeholder {USER_TYPE_PLACEHOLDER}")
     profile_values = _parse_profile_ini(profile_source)
     if profile_values.get("cost_profile") != profile:
         fail(
             f"Profile preset {profile_source.name} has cost_profile="
             f"{profile_values.get('cost_profile')!r} but --profile={profile}"
         )
+    # Inject runtime-only values (not part of the .ini profile presets).
+    profile_values["user_type"] = _validate_user_type(package_root, user_type)
     template_body = _render_template(template, profile_values)
 
     legacy_target = project_root / LEGACY_SETTINGS_FILE
@@ -822,7 +865,9 @@ def ensure_agent_settings(project_root: Path, package_root: Path, profile: str,
         return
 
     write_file(target, template_body)
-    success(f"{SETTINGS_FILE} created (cost_profile={profile})")
+    user_type_value = profile_values.get("user_type", "")
+    suffix = f", user_type={user_type_value}" if user_type_value else ""
+    success(f"{SETTINGS_FILE} created (cost_profile={profile}{suffix})")
 
 
 def ensure_vscode_bridge(project_root: Path, package_type: str, force: bool) -> None:
@@ -3130,6 +3175,17 @@ def parse_options(argv: list[str]) -> argparse.Namespace:
         default=DEFAULT_PROFILE,
         help=f"cost_profile value ({'|'.join(SUPPORTED_PROFILES)}, default: {DEFAULT_PROFILE})",
     )
+    parser.add_argument(
+        "--user-type",
+        dest="user_type",
+        default="",
+        help=(
+            "primary user-type for skill filtering (step-9 axis). "
+            "Valid ids: consultant | creator | developer | finance | "
+            "founder | gtm | ops. Default: empty (no filter, every skill "
+            "surfaces). Written to personal.user_type in .agent-settings.yml."
+        ),
+    )
     parser.add_argument("--force", action="store_true", help="overwrite existing files")
     parser.add_argument("--skip-bridges", action="store_true", help="only create .agent-settings.yml")
     parser.add_argument(
@@ -3354,7 +3410,7 @@ def _write_install_mode_marker(project_root: Path, mode: str) -> None:
         pass
 
 
-def install_minimal(target_root: Path, force: bool) -> int:
+def install_minimal(target_root: Path, force: bool, user_type: str = "") -> int:
     """Bootstrap the project-local override layer only (D2-compliant).
 
     Writes:
@@ -3421,8 +3477,16 @@ def install_minimal(target_root: Path, force: bool) -> int:
     if settings_dst.exists() and not force:
         skip(f"{SETTINGS_FILE} already exists (use --force to overwrite)")
     else:
-        settings_dst.write_text(settings_src.read_text(encoding="utf-8"), encoding="utf-8")
-        success(f"Wrote {SETTINGS_FILE}")
+        body = settings_src.read_text(encoding="utf-8")
+        if user_type:
+            body = body.rstrip() + (
+                "\n\n# --- Personal (step-9 user-type axis) ---\n"
+                "personal:\n"
+                f"  user_type: {user_type}\n"
+            )
+        settings_dst.write_text(body, encoding="utf-8")
+        suffix = f" (user_type={user_type})" if user_type else ""
+        success(f"Wrote {SETTINGS_FILE}{suffix}")
 
     # 3. install-mode marker (Step 8 A5) — authoritative state for
     # doctor --context and future install-aware tooling. Written even
@@ -3592,7 +3656,13 @@ def main(argv: list[str]) -> int:
         target_root = Path(
             opts.custom_path or opts.project or os.environ.get("PROJECT_ROOT") or os.getcwd()
         ).resolve()
-        return install_minimal(target_root, opts.force)
+        # Validate --user-type early so the minimal short-circuit fails
+        # fast on a bogus slug instead of writing a half-formed stub.
+        # _minimal_templates_root() returns <package_root>/templates/minimal;
+        # walk two parents up to reach the package root where user-types/ lives.
+        minimal_package_root = _minimal_templates_root().parent.parent
+        validated_user_type = _validate_user_type(minimal_package_root, opts.user_type)
+        return install_minimal(target_root, opts.force, validated_user_type)
 
     # Multi-signal scope detection (Phase 1.3) + scope resolution
     # (Phase 1.4). Order of precedence (highest first):
@@ -3670,9 +3740,13 @@ def _main_project_install(
         info(f"Package:  {package_root}")
         info(f"Type:     {package_type}")
         info(f"Profile:  {opts.profile}")
+        if opts.user_type:
+            info(f"UserType: {opts.user_type}")
         print()
 
-    ensure_agent_settings(project_root, package_root, opts.profile, opts.force)
+    ensure_agent_settings(
+        project_root, package_root, opts.profile, opts.force, opts.user_type
+    )
 
     # Install-mode marker (Step 8 A5) — full path flips any prior
     # minimal marker to "full" so doctor --context reflects the

package/scripts/install.sh

@@ -79,6 +79,13 @@ parse_args() {
             --skip-gitignore) SKIP_GITIGNORE=true; shift ;;
             --tools)   TOOLS="$2"; shift 2 ;;
             --tools=*) TOOLS="${1#*=}"; shift ;;
+            # --user-type is consumed by install.py (settings persistence).
+            # Accepted here so direct `bash scripts/install.sh --user-type=...`
+            # invocations from the `install` wrapper / standalone users do not
+            # trip the "Unknown argument" guard. Value is intentionally unused
+            # by the payload-sync stage.
+            --user-type)   shift 2 ;;
+            --user-type=*) shift ;;
             --minimal|--settings-only) MINIMAL=true; shift ;;
             --help|-h) show_help; exit 0 ;;
             *) log_error "Unknown argument: $1"; show_help; exit 1 ;;

package/scripts/mcp_server/prompts.py

@@ -18,7 +18,8 @@ helpers (caller decides whether to log).
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+import dataclasses
+from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Literal
 
@@ -36,6 +37,7 @@ PHASE_1_SKILLS: tuple[str, ...] = (
 )
 
 PromptKind = Literal["skill", "command"]
+UserTypeMatch = Literal["", "match", "universal", "outside"]
 
 
 @dataclass(frozen=True)
@@ -46,6 +48,12 @@ class SkillPrompt:
     field is the frontmatter `name:` value verbatim (e.g.
     `test-driven-development` or `research:report`); MCP wire names
     are derived in `to_mcp_prompt_meta` with `kind`-aware prefixing.
+
+    `recommended_for_user_types` mirrors the SKILL.md frontmatter
+    array (step-9 user-type axis). Empty tuple = universal (no
+    user-type constraint declared). `user_type_match` is the
+    cache-computed match label against the active `personal.user_type`
+    in `.agent-settings.yml`; empty string means filtering is disabled.
     """
 
     name: str
@@ -53,6 +61,8 @@ class SkillPrompt:
     body: str
     source: str
     kind: PromptKind = "skill"
+    recommended_for_user_types: tuple[str, ...] = ()
+    user_type_match: UserTypeMatch = ""
 
 
 def _project_root() -> Path:
@@ -84,6 +94,69 @@ def _strip_frontmatter(text: str) -> tuple[dict[str, str], str]:
     return meta, body.lstrip("\n")
 
 
+def _parse_inline_array(value: str) -> tuple[str, ...]:
+    """Parse `[a, b, c]` inline-array frontmatter value into a tuple.
+
+    Returns `()` for any malformed or empty value. Quotes around items
+    are stripped. This is intentionally a tiny parser — the canonical
+    schema for skill frontmatter is enforced upstream by
+    `task lint-skills` / `scripts/validate_frontmatter.py`.
+    """
+    v = value.strip()
+    if not (v.startswith("[") and v.endswith("]")):
+        return ()
+    inner = v[1:-1].strip()
+    if not inner:
+        return ()
+    items: list[str] = []
+    for raw in inner.split(","):
+        item = raw.strip().strip('"').strip("'")
+        if item:
+            items.append(item)
+    return tuple(items)
+
+
+def _load_active_user_type(root: Path) -> str:
+    """Read `personal.user_type` from `.agent-settings.yml`.
+
+    Returns `""` when the file is missing, the key is unset, or the
+    value is still the install-time placeholder (`__USER_TYPE__`).
+    Empty string disables the runtime filter (legacy behavior — every
+    skill surfaces with its native sort order).
+
+    Tiny line-based parser to avoid a `pyyaml` runtime dependency for
+    the loader (consistent with `_strip_frontmatter`). Only matches
+    `user_type:` directly under the top-level `personal:` block.
+    """
+    settings = root / ".agent-settings.yml"
+    if not settings.is_file():
+        return ""
+    try:
+        text = settings.read_text(encoding="utf-8")
+    except OSError:
+        return ""
+    in_personal = False
+    for raw in text.splitlines():
+        if not raw or raw.lstrip().startswith("#"):
+            continue
+        if not raw[0].isspace():
+            # Top-level key — flip in_personal based on whether it's `personal:`.
+            head = raw.split("#", 1)[0].strip().rstrip(":")
+            in_personal = head == "personal"
+            continue
+        if not in_personal:
+            continue
+        stripped = raw.strip()
+        if not stripped.startswith("user_type:"):
+            continue
+        _, _, value = stripped.partition(":")
+        value = value.split("#", 1)[0].strip().strip('"').strip("'")
+        if value.startswith("__") and value.endswith("__"):
+            return ""
+        return value
+    return ""
+
+
 def load_skill(name: str, root: Path | None = None) -> SkillPrompt:
     """Load a single skill by name. Raises FileNotFoundError if missing."""
     base = root or _project_root()
@@ -107,6 +180,9 @@ def _load_file(
         body=body.rstrip() + "\n",
         source=meta.get("source", "package"),
         kind=kind,
+        recommended_for_user_types=_parse_inline_array(
+            meta.get("recommended_for_user_types", "")
+        ),
     )
 
 
@@ -231,20 +307,48 @@ def to_mcp_prompt_meta(prompt: SkillPrompt) -> dict[str, Any]:
     Colons in command names (e.g. `research:report`) become `.` so
     the wire identifier is a single-segment dotted path that survives
     every MCP client we have tested.
+
+    When the user-type axis is active (`PromptCache` resolves a
+    non-empty `personal.user_type`), each prompt carries a
+    `user_type_match` label and the projected `_meta` surfaces it so
+    MCP clients can render the "outside <id> filter" collapse group.
+    Absent / empty label means filtering is off — meta is unchanged
+    from the legacy shape, preserving back-compat.
     """
     if prompt.kind == "command":
         wire = f"command.{prompt.name.replace(':', '.')}"
     else:
         wire = f"skill.{prompt.name}"
+    meta: dict[str, Any] = {"source": prompt.source, "kind": prompt.kind}
+    if prompt.user_type_match:
+        meta["user_type_match"] = prompt.user_type_match
     return {
         "name": wire,
         "title": prompt.name,
         "description": prompt.description,
         "arguments": [],
-        "_meta": {"source": prompt.source, "kind": prompt.kind},
+        "_meta": meta,
     }
 
 
+def _user_type_rank(prompt: SkillPrompt, user_type: str) -> tuple[int, UserTypeMatch]:
+    """Return `(sort_rank, match_label)` for the step-9 axis.
+
+    Ranks (lower sorts first):
+        0 = match     — user_type is in `recommended_for_user_types`
+        1 = universal — prompt declares no recommended_for_user_types
+        2 = outside   — declared, but user_type is not in the list
+
+    Caller must guarantee `user_type` is non-empty (filter is on).
+    """
+    declared = prompt.recommended_for_user_types
+    if not declared:
+        return (1, "universal")
+    if user_type in declared:
+        return (0, "match")
+    return (2, "outside")
+
+
 class PromptCache:
     """In-memory cache with mtime-based invalidation (B5 hot-reload).
 
@@ -264,6 +368,7 @@ class PromptCache:
         self._errors: list[str] = []
         self._signature: tuple[tuple[str, float], ...] = ()
         self._index: dict[str, SkillPrompt] = {}
+        self._active_user_type: str = ""
 
     def _current_signature(self) -> tuple[tuple[str, float], ...]:
         entries: list[tuple[str, float]] = []
@@ -278,10 +383,32 @@ class PromptCache:
             for path in sorted(cmd_root.rglob("*.md")):
                 if path.is_file():
                     entries.append((str(path), path.stat().st_mtime))
+        # `.agent-settings.yml` participates in the signature so a
+        # user_type flip (re-run install with a different --user-type)
+        # invalidates the cache without needing a SKILL.md touch.
+        settings = self._root / ".agent-settings.yml"
+        if settings.is_file():
+            entries.append((str(settings), settings.stat().st_mtime))
         return tuple(entries)
 
     def _refresh(self) -> None:
         prompts, errors = load_all_prompts(self._root)
+        user_type = _load_active_user_type(self._root)
+        self._active_user_type = user_type
+        if user_type:
+            # Tag every prompt with its match label and resort:
+            #   match (0) → universal (1) → outside (2), then wire name.
+            tagged: list[SkillPrompt] = []
+            for prompt in prompts:
+                _rank, label = _user_type_rank(prompt, user_type)
+                tagged.append(dataclasses.replace(prompt, user_type_match=label))
+            prompts = sorted(
+                tagged,
+                key=lambda p: (
+                    _user_type_rank(p, user_type)[0],
+                    to_mcp_prompt_meta(p)["name"],
+                ),
+            )
         self._prompts = prompts
         self._errors = errors
         self._index = {to_mcp_prompt_meta(p)["name"]: p for p in prompts}
@@ -299,6 +426,11 @@ class PromptCache:
         """Cached `(path, mtime)` tuples (Phase-6 F1 input). Call `get()` first."""
         return self._signature
 
+    @property
+    def active_user_type(self) -> str:
+        """Currently resolved `personal.user_type` (or `""` if no filter)."""
+        return self._active_user_type
+
     def lookup(self, wire_name: str) -> SkillPrompt | None:
         """Resolve an MCP wire name to its SkillPrompt, refreshing first."""
         self.get()

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

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/user-type-axis.schema.json",
+  "title": "User-type axis (install filter)",
+  "$comment": "Source: user-types/README.md § Schema. One file per user-type under user-types/<id>.yml. `id` MUST equal the filename stem. Owning roadmap: agents/roadmaps/step-9-user-types-axis.md.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "description"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "minLength": 2,
+      "maxLength": 40,
+      "description": "Stable slug. MUST equal the filename stem and the value used in skills' `recommended_for_user_types` frontmatter."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240,
+      "description": "One-line audience description shown in install.sh --help and the user-types/README.md index."
+    },
+    "primary_workflows": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_]*$",
+        "minLength": 2,
+        "maxLength": 60
+      },
+      "description": "Snake-case verb-phrases describing what this user-type does most days. Informs which skills surface first."
+    },
+    "default_skill_priority": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]*$",
+        "minLength": 2,
+        "maxLength": 60
+      },
+      "description": "Hand-curated short-list of 3–6 skill stems that should auto-load on `install.sh --user-type=<id>`."
+    },
+    "notes": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 480,
+      "description": "Optional one-line caveat (overlap with sibling user-types, legacy semantics, etc.)."
+    }
+  }
+}

package/scripts/sync_agent_settings.py

@@ -113,6 +113,12 @@ def main(argv: list[str] | None = None) -> int:
             print(f"error: unsupported profile {profile!r}", file=sys.stderr)
             return 2
         profile_values = load_profile(profile_dir, profile)
+        # Preserve existing user_type (step-9 axis) so the template's
+        # __USER_TYPE__ placeholder renders without forcing the user to
+        # re-pass --user-type on every sync. Empty string = no filter.
+        personal = user_data.get("personal") if isinstance(user_data.get("personal"), dict) else {}
+        existing_user_type = str(personal.get("user_type") or "") if personal else ""
+        profile_values["user_type"] = existing_user_type
         template_body = load_template(template_path, profile_values)
     except FileNotFoundError as exc:
         print(f"error: {exc}", file=sys.stderr)