Skip to main content
🗓️ Schedule discussionOpens Google Calendar — add attendees there.

Filter capability discovery by user role + artifact audience

OpenAuthor: @relbnsOwner: unassignedEffort: M

Problem​

bewith-docs is about to start serving two user populations. Today every artifact (agent, skill, command, hook, policy) is offered to everyone uniformly. The capability-awareness hook, /help-me, and any "I noticed you might want X" surface treat the user as anonymous.

This was fine while the developer-tooling roster was the whole platform. It is not fine starting now:

  • Gali, BeWith's product co-founder, is migrating her ABC-TOM multi-agent system into the platform. Her agents (spec-writer, gatekeeper, eventually an intake skill, a fast-track tool, an activation agent) target product workflows. When a developer is mid-edit on apps/external-gateway, an offer to "run spec-writer on this" is pure noise.
  • The inverse is worse. Gali types intent in Hebrew and the awareness hook offers her code-reviewer, process-guardian, /breakdown, MDX-safety hooks. None of these belong in her flow.

Without filtering, every new product artifact we land degrades the dev experience, and every dev artifact we already have degrades Gali's. Discoverability becomes a tax instead of a help.

Proposal​

Combine two complementary mechanisms — confirmed with the team on 2026-05-31:

(A) Per-user role, stored in personal memory. Default dev. Switchable via a new /role command, with permanent and session-only modes.

(B) Audience tag on every artifact frontmatter — audience: dev | product | both — required for any new agent / skill / command / policy. Existing artifacts get a bulk-tagging sweep.

Capability surfaces (the awareness hook, /help-me, future "I noticed" prompts) filter by intersection: a user with role: dev only sees artifacts tagged dev or both; role: product only sees product or both.

This is platform-level infrastructure that benefits any multi-role scenario, not just Gali. It lands as Phase 0.5 of the broader Gali ABC-TOM merge plan — the merge can build on top of it cleanly.

Why now / Why us​

  • The Gali merge is in active design (see /Users/ariel/.claude/plans/gali-merge-plan.md). Without role filtering, the first product agent we import (spec-writer) immediately starts polluting dev sessions. Better to land filtering before any product artifact does.
  • The mechanism is small (~five distinct pieces, all under a day each) and reversible (grep -L audience: lists what hasn't been tagged yet).
  • No other team owns this. The platform layer is mine.
  • It pays back beyond Gali: future role splits (e.g., a designer role, an analyst role) reuse the same audience field and the same /role command. No re-architecture needed.

Sketch of approach​

Five components, ideally two PRs — infrastructure first, sweep second:

  1. Frontmatter convention — extend docs/methodology/methodology-artifact-types.md to declare audience: dev | product | both as a required field on agents, skills, commands, and policies (not rules — rules are always-on; not hooks — hooks are infra). Lint rule: artifact missing audience warns; treated as both during the transition window.

  2. /role command + thin skill. Subcommands:

    • /role — show current role, with a one-line summary of who sees what.
    • /role dev / /role product — set permanent (writes to personal memory).
    • /role dev --session / /role product --session — current Claude Code session only. The command file lives at .claude/commands/role.md; the implementation skill at .claude/skills/role/SKILL.md.

  3. Personal-memory entry — user_role.md per developer at ~/.claude/projects/<project>/memory/. Default dev, auto-created on first session by the SessionStart hook if missing. Single field for now (role:), shaped to extend later (e.g., secondary_roles:, feature_flags:).

  4. Update the capability-awareness hook — read user_role.md + the per-artifact audience field; filter offers by intersection. Session-only override lives in ~/.claude/session-state.json (cleared on session end). Hook also surfaces a soft warning if an artifact has no audience (since untagged artifacts default to both, this is more nudge than block).

  5. Audience-tagging sweep — one-time pass over the ~19 existing artifacts:

    • audience: dev — code-reviewer, process-guardian, /breakdown, /end-session, all hooks, all rules in .claude/rules/team/, dev-flavored skills.
    • audience: both — /help-me, /new-artifact, /propose, /share-rule, /role itself.
    • audience: product — none yet (arrives with the Gali merge).

    Ships as a separate PR after the infrastructure lands, so the infrastructure PR stays small and easy to review.

Open questions​

  • Session-only storage location. Proposal: ~/.claude/session-state.json. Alternative: in-process variable held by the hook. The file approach survives a Claude Code restart mid-session; the in-process approach is cleaner but loses state on restart. Lean: file, since session restarts are common during long iterations.
  • Naming. /role vs /whoami vs /persona. Lean: /role — clearest verb, smallest surface.
  • Default role. Default dev for everyone, or auto-detect from git user.email. Lean: dev for everyone, no auto-detect — auto-detect adds magic that fails opaquely when someone's git config doesn't match their actual role.
  • Sweep timing. Same PR as the infrastructure, or follow-up. Lean: follow-up — keeps the first PR reviewable and isolates rollback if a sweep entry was miscategorized.
  • Rules and hooks. Should they carry audience too? They don't appear in discovery surfaces (rules are always-on, hooks are pre-tool gates), so a tag is pure metadata. Lean: skip them in v1, revisit if a use case appears.

Triage notes​

Filled in during triage. Empty until then.