convez.ai
MCP ServerAutomaçãoAvançado
Pavel-Tk

Priors Persona Gate

Pavel-Tk/priors-persona-gate

Valida trabalho de produto contra persona de cliente antes de apresentar

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-gate

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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:

HookEventBehaviour
Plan gatePreToolUse → ExitPlanModeDenies presenting a plan until ask_persona was called this turn.
Finish gateStopBlocks ending a turn that changed artifacts (Edit/Write/NotebookEdit/ExitPlanMode) without consulting the persona. Read-only / Q&A turns are not gated.
PrimingUserPromptSubmitInjects 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

  1. Claude Code (it ships its own Node.js; the hook scripts are .mjs, no extra runtime needed).

  2. 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.


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 #branch or #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.

VarRequiredPurpose
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_SEGMENTrecommendedSegment 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_PATHSoptional;-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_PATHS on ; 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:

  1. its directory is at/under one of the PRIORS_ENFORCE_PATHS prefixes, or
  2. a file named .priors-gate exists 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

  1. Plugin validates (CLI):
    claude plugin validate C:\Users\ptkac\priors-persona-gate --strict
    
  2. MCP tool is present — start Claude Code in an enforced project and confirm a tool named …priors…__ask_persona is available (/mcp or tool list).
  3. 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.
  4. Finish gate — make an edit without consulting, end the turn: blocked. Call ask_persona, then stop: passes.
  5. 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

SymptomLikely cause / fix
ask_persona not listedPRIORS_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 answersNo calibrated persona for that segment on the server (ask the Priors operator to calibrate one for your segment).
Gate never firesProject isn't in scope. Add a .priors-gate marker or a PRIORS_ENFORCE_PATHS prefix.
Gate fires in an unrelated repoA .priors-gate marker exists in an ancestor dir, or a PRIORS_ENFORCE_PATHS prefix is too broad.
MCP prompts for approval every sessionExpected on first use per server; approve it.
Changed plugin files but nothing updatedRun /reload-plugins, or restart the session.
Wrong segment in the reminder textSet/recheck PRIORS_PERSONA_SEGMENT; it must match the persona's segment tag on the server.

Notes & limits

  • The gates verify that ask_persona was called, not that the segment argument 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_persona MCP tool.
  • Hooks fail open on any internal error, so the gate can never hard-lock a session.
Ver o original no GitHub

Bom para

Relacionados