Persona Panel Skill

Invocation

The user invoked /persona-panel with arguments: $ARGUMENTS. Parse them before doing anything else — including before the Phase 0 bootstrap gate's side effects.

Positional argument (required):

• <target> — file path, directory, or range to review. Must be resolvable via validatePathInsideProject against the current project root (Phase 2). Relative paths are resolved from the project root. Globs are accepted (e.g. src/app/api/*.ts).

Recognized flags:

• --personas <names,...> — comma-separated subset of catalog names to include (e.g. physicist,ai-expert). Default: all personas discovered in .claude/personas/. Names are matched case-insensitively against <name>.md catalog files.
• --mode <voting|hard-gate|summary> — consolidation mode; the short forms are aliases of the Phase 4 mode names voting-quorum, hard-gate-threshold and coordinator-summary respectively. Default: voting-quorum. summary emits an explicit WARN that this mode adds one additional LLM call.
• --threshold <spec> — quorum spec. Accepted forms: M-of-N where M and N are integers 1..20, all, or any. Parsed by scripts/lib/persona-panel/threshold.mjs::parseThreshold(). Default: all for hard-gate-threshold. In voting-quorum the majority default of Phase 4 applies unless --quorum <M> overrides it.
• --quorum <M> — integer M-of-N override for voting-quorum (see Phase 4).
• --grounding <off|re-derive> — Grounding-Review mode (#730 Epic H). off (default): personas evaluate the target as-is. re-derive: each persona independently re-derives supporting sources via Read/Grep/Glob instead of trusting a "Sources" section the target may already assert, and reports them as derived_sources. Advisory-only in v1 — never influences final_verdict. See skills/persona-panel/persona-format.md § "Grounding Mode (optional)".
• --lines <start>-<end> — restrict the review to a line range of the target (validated in Phase 2: start ≤ end, both positive integers).
• --dry-run — resolve catalog and target, print the dispatch plan (persona names, models, target), do NOT call Agent(), do NOT write a sidecar. Exit 0 on success.

Validation errors (all exit 1):

• Missing <target>: missing required arg <target> — print the usage line and exit 1 without running any phase.
• Unknown flag (starts with -- but not in the list above): unknown flag: --<name>. Valid: --personas, --mode, --threshold, --quorum, --grounding, --lines, --dry-run.
• --mode value not in enum: invalid --mode value: '<value>'. Valid: voting, hard-gate, summary.
• --threshold value fails parseThreshold(): echo the parser error verbatim, e.g. invalid threshold 'foo': expected M-of-N (M,N integers 1..20), 'all', or 'any'.
• --grounding value not in enum: invalid --grounding value: '<value>'. Valid: off, re-derive.
• <target> outside project root: target path outside project: <path>.

Examples

/persona-panel src/app/api/invoices.ts

All .claude/personas/*.md are dispatched, voting consolidation, sidecar written.

/persona-panel src/app/api/invoices.ts --personas physicist,ai-expert

Only the physicist and ai-expert catalog entries are dispatched.

/persona-panel notes/draft.md --mode hard-gate --threshold all

All resolved personas must return PASS; a single FAIL produces a final FAIL verdict.

/persona-panel src/ --dry-run

Prints the planned dispatch list and exits 0 without calling Agent() or writing a sidecar.

/persona-panel docs/design-doc.md --grounding re-derive

Each persona re-derives its own supporting sources rather than trusting a "Sources" section already present in the input document (for example, docs/design-doc.md), reporting them as derived_sources. Advisory-only — final_verdict is unaffected. <!-- path-check: example -->

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.

Bundled Presets

The plugin ships one ready-made preset alongside the general templates/personas/ catalog: a 3-lens PM/Designer/Engineer panel at skills/persona-panel/presets/ (pm-lens.md, designer-lens.md, engineer-lens.md; tier domain-expert). Each lens audits one assumption dimension — value (PM), usability (Designer), feasibility (Engineer) — as three parallel domain-expert personas rather than one reviewer working all three serially.

Reach for it on feature/PRD/design reviews in a repo whose .claude/personas/ is empty or missing and no domain-specific catalog exists yet. It is a starting point, not a substitute — the per-repo catalog philosophy above still holds; copy and adapt into the project's own catalog rather than referencing the plugin copy in place.

Install:

mkdir -p .claude/personas
# Claude Code has no `plugin dir` subcommand — resolve the install path from the cache.
SO_DIR="$(dirname "$(find ~/.claude/plugins/cache -path '*session-orchestrator*' -name package.json 2>/dev/null | head -1)")"
cp "$SO_DIR/skills/persona-panel/presets/"*.md .claude/personas/

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."
3. Confirm the file exists and is readable. If not: exit 1 with "Target file not found: <path>".
4. 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': use the alias opus, which tracks the current Opus — pin a full ID only for a named reproducibility need (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, targetContent, groundingMode)>,
  tools: ["Read", "Grep", "Glob"]
})

Use buildPersonaPrompt(persona, target, targetContent, groundingMode) 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).

Grounding Mode (optional, --grounding <off|re-derive>, default off, #730 Epic H): when re-derive, groundingMode='re-derive' is passed to buildPersonaPrompt, which inserts a <grounding-instruction> block before <target-content> instructing the persona to independently re-derive supporting sources via Read/Grep/Glob rather than trusting a "Sources" section the target may already assert, and to report them as derived_sources in its JSON output. See persona-format.md § "Grounding Mode (optional)" for the full contract. v1 is advisory-only: diffGroundingSources() in consolidator.mjs never influences final_verdict.

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 target path with validatePathInsideProject(sidecarAbsPath, projectRoot) (H1 path guard) before writing.

Schema validation (security M3 — validate BEFORE write): Validate the sidecar object against agents/schemas/persona-panel-sidecar.schema.json using validateAgentOutput() from scripts/lib/agent-output-schema.mjs (AJV 2020-12). If validation fails: print the AJV errors to stderr and exit 1 — never write an invalid sidecar.

Write via writeJsonAtomic() from scripts/lib/io.mjs (atomic tmp-then-rename to prevent partial writes).

Sidecar schema shape (matched by agents/schemas/persona-panel-sidecar.schema.json):

{
  "run_id": "<string, 1-64 chars [a-z0-9-]>",
  "target": "<absolute path to reviewed file>",
  "personas_invoked": [
    {
      "name": "<persona name>",
      "version": "<string>",
      "model": "<full model ID used>",
      "prompt_hash": "<sha256 of canonicalized prompt — see persona-format.md>",
      "timestamp_start": "<ISO 8601>",
      "timestamp_end": "<ISO 8601>",
      "token_usage": {
        "input": "<integer>",
        "output": "<integer>",
        "cache_read": "<integer>",
        "cache_creation": "<integer>"
      }
    }
  ],
  "outputs": [
    {
      "persona_name": "<string>",
      "verdict": "<pass|fail|warn>",
      "rationale": "<string, max 4096 chars>",
      "recommendations": ["<string>"],
      "derived_sources": [
        { "path": "<string, optional — only when groundingMode='re-derive'>", "supports_claim": "<string, optional>" }
      ]
    }
  ],
  "consolidation": {
    "mode": "<voting-quorum|hard-gate-threshold|coordinator-summary>",
    "final_verdict": "<pass|fail|warn>",
    "pass_count": "<integer>",
    "fail_count": "<integer>",
    "warn_count": "<integer>",
    "dissenting_personas": ["<name>"],
    "audit_reason": "<string>",
    "aggregator_warning": "<string | null>",
    "grounding_diff": {
      "unconfirmed_author_sources": ["<string, optional — only when authorSources was supplied>"],
      "newly_derived": ["<string>"],
      "personas_reporting": "<integer>"
    }
  }
}

Token-usage contract (H4): Each personas_invoked entry records token_usage from the Anthropic API response: { input, output, cache_read, cache_creation }. Agents that do not return usage data record all fields as 0.

Final Report

Emit to stdout:

## Persona Panel Report

Target: <$TARGET>
Personas: <N> invoked | Mode: <mode>
Final verdict: <PASS|FAIL|WARN>

| Persona | Tier | Verdict | Rationale (excerpt) |
|---------|------|---------|---------------------|
| <name>  | ...  | pass    | ...                 |
| <name>  | ...  | fail    | ...                 |

Dissenting: <names or "none">
Sidecar: .orchestrator/persona-panel/<filename>.json

If final_verdict == "fail": exit with code 1 so CI and wave-executor hooks can gate on the result. If final_verdict == "warn": exit 0 with a warning line on stderr. If final_verdict == "pass": exit 0.

Critical Rules

• NEVER dispatch more than 20 personas per panel (security M2 cap).
• NEVER write a sidecar that fails schema validation — validate BEFORE write (security M3).
• NEVER skip validatePathInsideProject for the target path OR the sidecar output path (H1).
• NEVER use run_in_background: true for persona agents — the panel synthesis needs every reviewer's findings before Phase 4; background dispatch would add turn-juggling with no consumer for early results.
• ALWAYS validate model: fields from the catalog against MODEL_ID_RE + aliases (H2).
• ALWAYS run output_contract structural pre-check before ajv.compile() (H3).
• ALWAYS emit the aggregator_warning to BOTH stderr and sidecar when using coordinator-summary mode.
• ALWAYS treat missing persona verdict as "fail" — never silently skip or default to pass.
• Ties in consolidation go to FAIL, not pass or warn.

Anti-Patterns

• Running without a catalog — Phase 1 must gate on catalog existence.
• Using a single persona as a "quick check" — dispatch all catalog members unless --personas restricts deliberately. The value is the N-dimensional view.
• Ignoring dissenting personas in voting-quorum — record them in the sidecar even when the majority passes. They are the signal for trend-tracking (#459).
• Writing the sidecar before schema validation passes — invalid sidecars corrupt trend analysis.
• Calling ajv.compile() without the AbortSignal timeout — pathological schemas can block the event loop indefinitely.

See Also

• scripts/lib/persona-panel/threshold.mjs — parseThreshold() for --threshold specs
• agents/schemas/persona-panel-sidecar.schema.json — sidecar JSON Schema (Draft 2020-12)
• scripts/lib/persona-panel/catalog-loader.mjs — loadCatalog() implementation
• scripts/lib/persona-panel/persona-runner.mjs — buildPersonaPrompt() implementation
• scripts/lib/persona-panel/consolidator.mjs — consolidation logic (3 modes)
• skills/persona-panel/persona-format.md — persona file format specification
• skills/wave-executor/wave-loop.md — Persona-Gate hook (Phase 5b/3b, added in #458)
• scripts/lib/path-utils.mjs — validatePathInsideProject()
• scripts/lib/io.mjs — writeJsonAtomic()
• scripts/lib/agent-frontmatter.mjs — MODEL_ID_RE, ALLOWED_MODEL_ALIASES