persona-panel

Persona Panel Skill

Overview

Persona Panel runs any number of catalog-defined personas in parallel against a single target (file, document, or output range). Each persona agent produces a structured verdict. The coordinator consolidates the verdicts into a final result using one of three configurable modes and persists a sidecar record for audit and trend-tracking.

The catalog lives in .claude/personas/*.md — per-repo, never plugin-central. This is intentional: climate-research repos need physicists; SaaS repos need buyer personas; compliance repos need auditors. Plugin-central catalogs block that diversity.

Phase 0: Bootstrap Gate

Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to skills/_shared/bootstrap-gate.md for the full HARD-GATE constraints. </HARD-GATE>

Phase 1: Catalog Discovery

Load the per-repo persona catalog via loadCatalog() from scripts/lib/persona-panel/catalog-loader.mjs.

Failure modes — all are hard stops:

(a) .claude/personas/ directory missing:

Error (exit 2): .claude/personas/ directory not found in this repo.
Create persona files there to use /persona-panel.
See templates/personas/ for starter templates (issue #458).

(b) .claude/personas/ present but empty (no .md files):

Error (exit 2): .claude/personas/ exists but contains no persona files (*.md).
Add at least one persona file to use /persona-panel.
See templates/personas/ for starter templates (issue #458).

(c) --personas <name> arg specified but name not found in catalog:

Error (exit 1): Persona "<name>" not found in .claude/personas/.
Available personas: <list of names from catalog>.

(d) Malformed YAML frontmatter in a catalog file:

Error (exit 1): Malformed YAML in .claude/personas/<filename>.md at line <N>: <error>.
Fix the frontmatter before running /persona-panel.

Model validation (H2 security guard): The catalog loader validates each persona's model: field against MODEL_ID_RE + ALLOWED_MODEL_ALIASES from scripts/lib/agent-frontmatter.mjs at load time. A persona with an invalid model string triggers failure mode (d) with an informative message: "invalid model '<value>' — must be a Claude model ID or alias (inherit|sonnet|opus|haiku)".

output_contract structural pre-check (H3 security guard): After YAML parse and before AJV compile, the loader inspects each persona's output_contract object for forbidden keys: $ref, $defs, allOf, anyOf. Any occurrence triggers failure mode (d). This structural pre-check runs BEFORE ajv.compile(). The AJV compile call wraps in a 2-second AbortSignal timeout to guard against pathological schema inputs.

After successful load, emit a one-line status banner:

Catalog: [N] personas loaded from .claude/personas/. Tier breakdown: domain-expert [N], buyer-persona [N], compliance [N], custom [N].

If --personas <names> was passed, filter to the named subset. Report the active set.

Phase 2: Target-Input-Resolution

Resolve the <target-path> argument against the project root.

1. Expand to absolute path (relative inputs are resolved from git rev-parse --show-toplevel).
2. Call validatePathInsideProject(absolutePath, projectRoot) from

scripts/lib/path-utils.mjs. This function performs a two-phase lexical + realpath guard.

• If the path resolves outside the project root: exit 1 with message

"Target path escapes project root — /persona-panel only reviews files inside the repo."

1. Confirm the file exists and is readable. If not: exit 1 with "Target file not found: <path>".
2. If a range was specified (--lines <start>-<end>), validate that start ≤ end and both are

positive integers.

Store the resolved absolute path as $TARGET.

Phase 3: Parallel Dispatch

Dispatch one Agent per persona from the active catalog set.

Model selection per persona:

• If persona.model is a full Claude model ID (MODEL_ID_RE): use it as-is.
• If persona.model is opus or unset AND persona.tier == 'domain-expert': override to

claude-opus-4-7 (empirically validated — Opus finds real problems Sonnet misses; see vault learning [[persona-opus-finds-real-failing-cibadge]]).

• Otherwise: use the persona's declared model alias.

Agent dispatch contract:

Agent({
  subagent_type: "general-purpose",
  model: <resolved model ID>,
  prompt: <buildPersonaPrompt(persona, $TARGET)>,
  tools: ["Read", "Grep", "Glob"]
})

Use buildPersonaPrompt(persona, target) from scripts/lib/persona-panel/persona-runner.mjs to compose the prompt. The runner wraps evaluation_criteria entries in <persona-criteria>...</persona-criteria> delimiters (security M1: persona body is treated as data, not free-form instructions; see persona-format.md for the full rationale).

Concurrency cap (security M2): Maximum 20 personas per panel run. If the active set exceeds 20, emit a warning and truncate to the first 20 alphabetically:

Warning: Persona set truncated to 20 (cap). Omitted: <names>.

run_in_background: false for all agents. Do not proceed to Phase 4 until ALL agents complete.

Dispatch summary line (before dispatch):

Dispatching [N] persona agents in parallel. Target: <$TARGET>. Mode: <consolidation-mode>.

Phase 4: Konsolidierung (Consolidation)

After all agents complete, run consolidation via scripts/lib/persona-panel/consolidator.mjs.

Three consolidation modes (set by --mode arg, default: voting-quorum):

voting-quorum (default)

Deterministic M-of-N threshold. Default M = ceil(N / 2) + 1 (simple majority). Override with --quorum <M>.

• Count personas whose verdict == "pass".
• If pass-count >= M: final-verdict = "pass".
• If pass-count < M: final-verdict = "fail".
• Tie: impossible when M > N/2. If M == ceil(N/2) exactly and count == M - 1: final-verdict =

"fail" (ties go to FAIL).

hard-gate-threshold

Strict M-of-N where default M == N (unanimity). Override with --threshold <M>.

• If ALL N personas pass: final-verdict = "pass".
• If any persona returns "fail": final-verdict = "fail".
• If any persona returns "warn" and no failures: final-verdict = "warn".
• Tie-break: ties go to FAIL.

coordinator-summary

LLM aggregate via coordinator. The coordinator reads all persona outputs and produces a synthesized summary verdict.

WARN (required — emit to BOTH stderr AND sidecar consolidation.aggregator_warning):

Warning: coordinator-summary mode triggers an additional LLM call (the coordinator aggregation
step). This incurs extra token cost. Use voting-quorum or hard-gate-threshold for deterministic,
zero-extra-LLM-call consolidation.

For each persona output, parse the structured block (see persona-format.md Output Contract). Validate that verdict ∈ {"pass", "fail", "warn"} — if a persona output lacks a valid verdict, treat it as "fail" and record it in dissenting_personas with reason "missing-verdict".

Emit a consolidation summary:

Consolidation ([mode]): [pass-count] pass / [fail-count] fail / [warn-count] warn — Final: <verdict>
Dissenting: <names> (if any)

Phase 5: Sidecar-Persist + Report

Write the sidecar record and emit the final report.

Sidecar Persistence

Run ID generation (H1 security guard):

const runId = randomUUID().slice(0, 8); // format: [a-z0-9-]{8}

Validate: runId MUST match /^[a-z0-9-]{1,64}$/. Reject and regenerate if it does not.

Timestamp format for filename: ^\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}(\.\d+)?Z?$ (filename-safe ISO — colons replaced with hyphens).

Example: 2026-05-20T14-30-00Z-a1b2c3d4.json

Path: .orchestrator/persona-panel/<isoTs>-<runId>.json

Validate the sidecar t