# Epic: Project persona registry and generated domain personas

Backlog Item ID: PERSONA-REGISTRY-EPIC-20260517

## Epic Story

As a project owner, I want Open Orchestra to register, govern, and activate
project-specific personas through APIs and UI instead of manual markdown edits,
so that each project can orchestrate the right domain experts, reviewers, and
delivery roles for its own context.

## Problem

Open Orchestra ships with software delivery roles, but real projects may need
domain personas that do not fit a fixed role catalog. A music production project
may need producers, mastering QA, and rights reviewers. A neural network project
may need ML researchers, MLOps, data stewards, and AI safety reviewers. A medical
project may need clinical SMEs, medical reviewers, privacy, compliance, and
regulatory reviewers.

Those personas should not require users to open or edit markdown files manually.
They also should not be blindly activated because a generated profile sounds
plausible. Projects need a registry, generation workflow, governance model, and
runtime activation rules.

## MVP Outcome

- Local persona registry stored in project workflow state and exportable to
  version-controlled artifacts.
- CLI/API operations to list, show, create, update, generate, approve,
  deactivate, export, and import personas.
- Generated personas start as drafts and require human approval before runtime
  activation.
- Runtime activation uses task signals, phase, required roles, risk level, and
  persona triggers.
- Regulated or high-risk personas can advise and review, but cannot approve
  regulated outcomes unless a human approver is configured.
- Web console can manage project personas without editing markdown files.
- Offline-first operation works from packaged baselines and local project
  context; internet or SaaS enrichment is optional.

## To-Be Outcome

- SaaS-backed persona registry with tenant isolation, versioning, approval
  workflows, audit trails, quality scores, and reusable persona packs.
- Domain packs for software, music/audio, ML/AI, healthcare, data, security,
  operations, education, legal/compliance, and other project types.
- Optional state-of-the-art refresh pipeline that proposes persona updates from
  curated references, prompt bank entries, lessons learned, and approved domain
  packs.
- Guarded supervisor can detect missing personas from project activity and
  propose draft personas or capability changes.
- Runtime scheduler and budget policies constrain generation, enrichment, and
  multi-agent activation.
- Chaos and resilience validation proves persona workflows degrade safely when
  providers, registries, approvals, budgets, or context sources fail.

## Persona Model

Minimum fields:

- `id`
- `displayName`
- `roleFamily`
- `domain`
- `purpose`
- `responsibilities`
- `activationTriggers`
- `workflowPhases`
- `requiredCapabilities`
- `optionalCapabilities`
- `requiredSkills`
- `authorityLevel`: advisory, reviewer, approver, executor
- `approvalConstraints`
- `evidenceExpectations`
- `securityConstraints`
- `regulatoryScope`
- `riskLevel`
- `sourcePolicy`: packaged, project, generated, imported, external
- `version`
- `status`: draft, active, deprecated, rejected
- `createdBy`
- `approvedBy`
- `provenance`

## Proposed Child Stories

### Story 1: Local Persona Registry API

As a project owner, I want a typed local persona registry API so that personas
can be managed without editing markdown files manually.

Acceptance criteria:

- Provides CLI/API operations: list, show, create, update, deactivate, approve,
  reject, export, and import.
- Persists project personas in workflow state with schema validation and
  deterministic IDs.
- Supports versioning and immutable approval provenance.
- Prevents duplicate active personas with the same project ID and role family.
- Exports approved personas to a portable version-controlled artifact.
- Rejects malformed, oversized, conflicting, or partially imported persona data
  without corrupting the registry.
- Includes unit tests for create, update, approval, deactivation, import/export,
  invalid schema, and duplicate prevention.

Suggested size: M.

Suggested owners: Architect, Developer, QA.

### Story 2: Persona Generation Assistant

As a project owner, I want Open Orchestra to generate draft personas from project
needs and context so that I can define domain roles quickly without starting from
a blank file.

Acceptance criteria:

- Generates draft personas from a requested role, domain, task context,
  workflow phase, existing roles, local standards, lessons learned, and approved
  prompt bank entries.
- Uses offline packaged baselines first and optional external enrichment only
  when enabled.
- Marks generated personas as draft and inactive by default.
- Records provenance: prompt id, context sources, model/provider when available,
  generated timestamp, and reviewer requirements.
- Applies prompt-injection and secret redaction checks to context before
  generation.
- Includes chaos/resilience tests for provider timeout, provider unavailable,
  unsafe context, prompt registry unavailable, and budget exhaustion.
- Includes tests for draft status, provenance, source filtering, offline mode,
  and blocked unsafe context.

Suggested size: L.

Suggested owners: Product Owner, Architect, Security, Developer, QA.

### Story 3: Domain Persona Packs

As a project owner, I want reusable domain persona packs so that non-software
projects can bootstrap relevant expert profiles.

Acceptance criteria:

- Defines packaged baseline packs for software delivery, music/audio, ML/AI,
  healthcare, data/analytics, security, operations, and compliance.
- Packs are compact metadata, not long prompt bodies.
- Each pack declares default personas, capabilities, activation triggers,
  evidence expectations, and risk constraints.
- Healthcare and other regulated packs mark expert personas as human-approval
  required for regulated decisions.
- Includes tests for pack loading, filtering by domain, and high-risk activation
  constraints.

Suggested size: M.

Suggested owners: Product Manager, Architect, Compliance/Privacy, QA.

### Story 4: Runtime Persona Activation

As a workflow runtime, I want to activate personas only when a task, phase, risk,
or required role needs them so that context stays bounded and relevant.

Acceptance criteria:

- Resolves active personas from task signals, required roles, optional roles,
  phase, paths, domain, risk level, and explicit user request.
- Does not load every persona for every task.
- Returns activation rationale and skipped-persona rationale.
- Integrates with capability and skill resolution without duplicating
  hardcoded role maps.
- Blocks unapproved, rejected, deprecated, or policy-ineligible personas.
- Includes chaos/resilience tests for corrupted registry state, missing
  approvals, disabled persona packs, and provider-independent offline
  activation.
- Includes tests for phase-scoped activation, domain triggers, no-match cases,
  high-risk human approval, and capability resolution.

Suggested size: M.

Suggested owners: Architect, Developer, QA.

### Story 5: Persona Governance and Safety Gates

As a security and compliance reviewer, I want persona creation and activation to
respect authority boundaries so that generated personas cannot approve unsafe or
regulated outcomes.

Acceptance criteria:

- Requires human approval before any generated persona becomes active.
- Requires explicit human approver mapping for regulated authority levels.
- Prevents generated medical, legal, financial, privacy, or regulatory personas
  from issuing final approval unless policy allows a configured human approver.
- Records audit events for generation, approval, rejection, activation, and
  deactivation.
- Adds security review when personas touch secrets, PII, PHI, financial data,
  regulated decisions, network calls, or external references.
- Includes chaos/resilience tests for approval race conditions, missing approver
  mappings, policy engine failure, audit write failure, and denied regulated
  authority escalation.
- Includes tests for approval policy, audit events, blocked activation, and
  unsafe authority escalation.

Suggested size: M.

Suggested owners: Security, Compliance/Privacy, Architect, QA.

### Story 6: Web Console Persona Management

As a human user, I want to manage project personas in the web console so that I
can review and approve personas without editing local files.

Acceptance criteria:

- Adds a Personas management page or section with list, detail, create,
  generate, edit draft, approve, reject, deactivate, export, and import flows.
- Shows persona status, authority level, domain, risk, triggers, capabilities,
  evidence expectations, and approval state.
- Provides empty, loading, error, success, and recovery states.
- Uses tooltips for authority level, regulated scope, activation triggers, and
  evidence expectations.
- Includes resilience coverage for API timeout, failed generation, rejected
  approval, import validation failure, and stale registry data.
- Includes Playwright coverage for list, create draft, approve, reject, and
  high-risk warning flows.

Suggested size: L.

Suggested owners: UX/UI Designer, Developer, QA, Technical Writer.

### Story 7: Persona Documentation and User Guide

As a user, I want clear persona registry documentation so that I understand how
to define domain experts, generated personas, and approval constraints.

Acceptance criteria:

- Documents CLI and API usage for persona registry operations.
- Explains packaged personas, generated drafts, approval, activation, and
  regulated-domain limits.
- Includes examples for software, music/audio, ML/AI, and healthcare projects.
- Documents offline-first behavior and optional SaaS/external enrichment.
- Updates the public site docs if persona management becomes user-facing.

Suggested size: S.

Suggested owners: Technical Writer, Product Owner, QA.

## Epic Acceptance Criteria

- Persona registry avoids manual markdown editing for normal persona management.
- Persona generation produces draft, reviewable personas, not automatically
  active authorities.
- Runtime activation is bounded by task need, phase, role, risk, and project
  domain.
- Regulated domains require explicit human approval policies.
- Offline-first mode works without internet access.
- SaaS/external enrichment is optional and tenant-scoped when enabled.
- Child stories are independently estimable and testable.
- Chaos testing validates safe degradation for persona registry, runtime
  activation, generation, governance, and web console flows.

## Non-Goals

- Replacing built-in delivery roles in the first release.
- Building a full SaaS registry in the MVP.
- Allowing generated personas to approve regulated clinical, legal, financial,
  or compliance outcomes without a configured human approver.
- Making internet access mandatory for persona generation.
- Storing raw prompts or sensitive project context by default.

## Risks

- Generated personas may sound authoritative without enough domain validation.
- Prompt injection from lessons learned, issues, docs, or external references.
- Secret or sensitive data leakage during persona generation.
- Context bloat if runtime activation loads too many personas.
- Tenant and regulatory boundary violations in SaaS mode.
- Duplicate or conflicting personas if registry ownership is unclear.
- Workflow degradation if multiple agents generate or activate personas while
  providers, approval stores, or prompt/context registries are unavailable.

## Chaos And Resilience Testing

Persona features should load the `chaos-resilience-testing` skill for controlled
failure scenarios where they affect runtime behavior or authority. The goal is
not random fault injection in the first MVP; it is deterministic chaos-style
validation that proves the product fails closed, preserves auditability, and
keeps offline operation usable.

Minimum scenarios:

- provider timeout or unavailable model during persona generation;
- prompt bank, lessons, or external enrichment source unavailable;
- malformed, oversized, or partially imported persona registry data;
- concurrent approval/update attempts for the same persona;
- missing human approver mapping for regulated authority;
- budget envelope exhausted before or during generation;
- policy engine denies activation or fails closed;
- audit/event write failure during approval or activation;
- web console API timeout or stale registry response;
- offline mode with no external network access.

Expected behavior:

- generated personas remain `draft` unless approval succeeds;
- regulated personas cannot approve final outcomes without configured human
  authority;
- runtime activation skips unsafe personas and records the rationale;
- unavailable optional sources degrade with explicit evidence instead of
  blocking local workflows;
- failures produce QA evidence that maps back to the story acceptance criteria.

## Suggested Epic Size

XL for full epic.

MVP slice: L.

Recommended first implementation order:

1. Dynamic UX phase routing for user-facing work
   (`UX-DYNAMIC-PHASE-ROUTING-20260517`) before the persona web console story.
2. Local Persona Registry API.
3. Runtime Persona Activation.
4. Persona Governance and Safety Gates.
5. Persona Generation Assistant.
6. Web Console Persona Management.
7. Domain Persona Packs.
8. Documentation and user guide.

## Related Workflow Story

`UX-DYNAMIC-PHASE-ROUTING-20260517` should add dynamic UX routing for
user-facing tasks before persona management UI is implemented. The current
workflow can recommend `ux_review` after implementation, but it does not yet
support a pre-architecture `ux_design` phase or BA/PO validation of UX artifacts
before architecture.

Expected target sequence for user-facing work:

```txt
po/ba -> ux_design -> po_validation -> architect -> developer -> qa -> ux_review -> release
```

The first implementation may keep this advisory when a task or global
`workflow.phaseSequence` is manually configured, but the phase planner should
make the recommendation explicit and explain why UX must provide design inputs
before architecture for UI-heavy work.