Priors Persona Gate
Pavel-Tk/priors-persona-gate
Valida trabalho de produto contra persona de cliente antes de apresentar
Ver no GitHubMCP server que força o agente a consultar uma persona de cliente calibrada antes de apresentar planos ou finalizar trabalhos. Integra-se ao Priors para feedback baseado em dados de entrevistas reais, tratando a opinião da persona como sugestiva e nunca validadora.
Instalação
npx convez-ai Pavel-Tk/priors-persona-gate1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Validar planos de produto contra feedback de persona calibrada
- Garantir alinhamento com segmento-alvo antes de finalizar artefatos
- Obter feedback iterativo baseado em dados de entrevistas reais
Veredito

Ferramenta specializada para equipes que usam Priors e Claude Code, adicionando validação de produto contra personas de cliente. Requer infraestrutura Priors hospedada e é mais adequada para fluxos de desenvolvimento iterativo com feedback estruturado.
README
A tradução para o português deste README ainda está na fila.
Priors Persona Gate
A Claude Code plugin that forces the agent to consult a calibrated customer
persona — via the hosted Priors ask_persona MCP tool —
before it presents a plan or finishes product work. The persona is a synthetic
customer tuned to real interview data for a target segment; its feedback is treated
as suggestive, never validating.
This repo doubles as a single-plugin marketplace: point Claude Code at it and install in two commands.
TL;DR install
# 1. add this repo as a marketplace (pick the form that matches where the repo lives)
/plugin marketplace add <owner>/<repo> # GitHub shorthand
/plugin marketplace add https://github.com/<owner>/<repo>.git
/plugin marketplace add C:\Users\ptkac\priors-persona-gate # local clone (Windows)
# 2. install the plugin from that marketplace
/plugin install priors-persona-gate@priors-persona-gate
Both the marketplace name and the plugin name are priors-persona-gate,
so the install target is always priors-persona-gate@priors-persona-gate.
Then set the environment variables and opt your project in. That's it — hooks and the bundled MCP server activate on the next session.
What it does
It bundles the hosted Priors MCP server (so the ask_persona tool is available to
the agent) and wires three hooks:
| Hook | Event | Behaviour |
|---|---|---|
| Plan gate | PreToolUse → ExitPlanMode | Denies presenting a plan until ask_persona was called this turn. |
| Finish gate | Stop | Blocks ending a turn that changed artifacts (Edit/Write/NotebookEdit/ExitPlanMode) without consulting the persona. Read-only / Q&A turns are not gated. |
| Priming | UserPromptSubmit | Injects a reminder + the configured segment so the agent asks early and rarely hits a hard block. |
Both gates verify that the persona was consulted (any ask_persona tool call
since the last user message), not the exact arguments. All hooks fail open: a
malformed transcript or unexpected payload can never lock a session.
The bundled customer-persona-check skill teaches the agent when/how to call
ask_persona, how to fold the answer in, and the standing caveat.
Prerequisites
-
Claude Code (it ships its own Node.js; the hook scripts are
.mjs, no extra runtime needed). -
A reachable hosted Priors instance with:
- the MCP service exposed publicly (ends in
/mcp), - at least one calibrated persona for your target segment,
- a workspace API key (
pk_…).
Setting that up is the server operator's job (separate private setup notes — not included in this public repo). You need four values from them: the MCP URL, the
pk_key, the segment tag, and (optionally) which project paths to gate. - the MCP service exposed publicly (ends in
Install — full walkthrough
1. Get the repo where Claude Code can reach it
Use any of:
- GitHub (push this folder to a repo), then
add <owner>/<repo>. - Any Git URL:
https://…/repo.git,git@…:owner/repo.git, optionally pinned with#branchor#tag. - Local clone — no Git host required. Just point at the directory on disk.
2. Add the marketplace and install
/plugin marketplace add C:\Users\ptkac\priors-persona-gate
/plugin install priors-persona-gate@priors-persona-gate
Install scope (optional):
/plugin install priors-persona-gate@priors-persona-gate --scope user # default, all projects
/plugin install priors-persona-gate@priors-persona-gate --scope project # this repo's .claude/settings.json
/plugin install priors-persona-gate@priors-persona-gate --scope local # .claude/settings.local.json
On first use you'll get a per-server approval prompt for the bundled priors MCP
server (same as any .mcp.json server). Approve it. If you change plugin files
mid-session, run /reload-plugins.
3. Configure environment variables
The plugin reads these from the environment — both Claude Code (for ${VAR}
expansion in .mcp.json) and the hook scripts (process.env) must see them.
| Var | Required | Purpose |
|---|---|---|
PRIORS_MCP_URL | ✅ | Hosted Priors MCP endpoint, e.g. https://priors-mcp.<region>.azurecontainerapps.io/mcp |
PRIORS_API_KEY | ✅ | Workspace key pk_… (sent as Authorization: Bearer) |
PRIORS_PERSONA_SEGMENT | recommended | Segment tag the agent must query — use the exact value your Priors operator hands off (it must match a calibrated persona's segment tag on the server), e.g. accountant |
PRIORS_ENFORCE_PATHS | optional | ;-separated project path prefixes to gate. If unset, use a .priors-gate marker file (next section). |
Windows (PowerShell) — persists across sessions:
setx PRIORS_MCP_URL "https://priors-mcp.delightfulhill-7fed9d8f.northeurope.azurecontainerapps.io/mcp"
setx PRIORS_API_KEY "pk_xxxxxxxxxxxx"
setx PRIORS_PERSONA_SEGMENT "accountant"
# optional, gate only these project roots:
setx PRIORS_ENFORCE_PATHS "C:\Software_projects\Priors;C:\work\my-product"
# close and reopen the terminal / Claude Code so the new environment is picked up
macOS / Linux (bash/zsh) — add to your shell profile:
export PRIORS_MCP_URL="https://…/mcp"
export PRIORS_API_KEY="pk_xxxxxxxxxxxx"
export PRIORS_PERSONA_SEGMENT="accountant"
export PRIORS_ENFORCE_PATHS="/home/me/Priors:/home/me/my-product" # note: paths joined by ';' on all OSes
The plugin splits
PRIORS_ENFORCE_PATHSon;regardless of OS.
4. Turn the gate on for a project
Enforcement is off by default everywhere, so the plugin can be installed at user scope without gating unrelated work. A project is enforced when either:
- its directory is at/under one of the
PRIORS_ENFORCE_PATHSprefixes, or - a file named
.priors-gateexists in the project root (or any ancestor).
The marker file can be empty — its presence is the opt-in:
# from the project you want gated
New-Item -ItemType File .priors-gate
Outside scope, the hooks no-op (no injection, no blocks).
Verify the install
- Plugin validates (CLI):
claude plugin validate C:\Users\ptkac\priors-persona-gate --strict - MCP tool is present — start Claude Code in an enforced project and confirm a
tool named
…priors…__ask_personais available (/mcpor tool list). - Plan gate — in plan mode, try to finish the plan without asking: it should be
denied with an instruction to call
ask_persona. Call it, retry — it passes. - Finish gate — make an edit without consulting, end the turn: blocked. Call
ask_persona, then stop: passes. - Scope — in a non-enforced directory, no injection and no blocks.
How the agent is expected to respond
When gated, the deny/block reason tells the agent to call
ask_persona(segment="<your segment>") and retry. The bundled skill explains how to
ask a sharp, decision-relevant question, how to weigh the fidelity-stamped answer,
and to treat synthetic input as suggestive, never validating.
Repository layout
priors-persona-gate/
├── .claude-plugin/
│ ├── plugin.json # plugin manifest
│ └── marketplace.json # makes the repo installable as a marketplace
├── .mcp.json # bundles the hosted Priors MCP server (env-driven)
├── hooks/
│ └── hooks.json # wires the three hooks
├── scripts/
│ ├── lib.mjs # scope check + transcript parsing (fail-soft)
│ ├── check-persona.mjs # the hard gate (plan + stop)
│ └── inject-context.mjs # soft priming (UserPromptSubmit)
├── skills/
│ └── customer-persona-check/
│ └── SKILL.md # how the agent should consult the persona
└── README.md
Troubleshooting
| Symptom | Likely cause / fix |
|---|---|
ask_persona not listed | PRIORS_MCP_URL / PRIORS_API_KEY unset, or the hosted MCP is unreachable. Check the Priors MCP /healthz. On Azure the priors-mcp app scales to zero — the first call after idle is slow (cold start), not a failure. |
| Empty answers | No calibrated persona for that segment on the server (ask the Priors operator to calibrate one for your segment). |
| Gate never fires | Project isn't in scope. Add a .priors-gate marker or a PRIORS_ENFORCE_PATHS prefix. |
| Gate fires in an unrelated repo | A .priors-gate marker exists in an ancestor dir, or a PRIORS_ENFORCE_PATHS prefix is too broad. |
| MCP prompts for approval every session | Expected on first use per server; approve it. |
| Changed plugin files but nothing updated | Run /reload-plugins, or restart the session. |
| Wrong segment in the reminder text | Set/recheck PRIORS_PERSONA_SEGMENT; it must match the persona's segment tag on the server. |
Notes & limits
- The gates verify that
ask_personawas called, not that thesegmentargument matches — deliberately, to avoid brittleness. (Asserting the segment is possible if you want it stricter.) - No changes are made to the Priors repository; the gate uses the existing read-only
ask_personaMCP tool. - Hooks fail open on any internal error, so the gate can never hard-lock a session.