Custom Persona Design Guide

A step-by-step guide to designing, implementing, testing, and documenting custom personas for the FCC framework. This guide covers the complete lifecycle from initial R.I.S.C.E.A.R. specification through plugin registration and documentation generation.

---

Overview

Creating a custom persona involves seven steps:

1. Define the R.I.S.C.E.A.R. specification (10 components)
2. Create a 56-dimension profile
3. Add cross-reference matrix entries
4. Assign a constitution
5. Register as a plugin (optional)
6. Write tests
7. Generate documentation

Each step builds on the previous one. By the end, you will have a fully integrated persona that participates in workflows, appears in dashboards, and is discoverable through semantic search.

---

Step 1: Define the R.I.S.C.E.A.R. Specification

Every persona requires a complete R.I.S.C.E.A.R. specification with all 10 components. Create a YAML file in src/fcc/data/personas/ or in your plugin's data directory.

Minimal YAML Template

personas:
  - id: MYP            # 2-4 uppercase letters, unique across all personas
    name: My Persona
    fcc_phase: Create   # One of: Find, Create, Build, Critique, Ops, Orchestration
    role_title: Senior Specialist
    color: "#FF6B6B"    # Hex color for dashboard display
    category: custom    # Category name (existing or new)
    riscear:
      role: >-
        One-paragraph description of what this persona does. Include the
        domain context and how it fits into a larger workflow.
      inputs:
        - Input source 1 (e.g., "Architecture diagrams and design documents")
        - Input source 2 (e.g., "Stakeholder requirements and feedback")
        - Input source 3 (e.g., "Existing codebase and API documentation")
      style: >-
        How this persona communicates. Describe tone, formatting preferences,
        and documentation patterns.
      constraints:
        - Constraint 1 (use RFC 2119 language: MUST, SHOULD, MAY)
        - Constraint 2
        - Constraint 3
      expected_output:
        - Output 1 (e.g., "Analysis report with findings and recommendations")
        - Output 2 (e.g., "Configuration files with inline documentation")
      archetype: The Descriptor  # "The [Noun]" format
      responsibilities:
        - Responsibility 1
        - Responsibility 2
        - Responsibility 3
      role_skills:
        - Skill 1 (e.g., "Python")
        - Skill 2 (e.g., "Data modeling")
      role_collaborators:
        - persona_id: RC
          relationship: upstream
          description: "Receives research inventory from RC"
        - persona_id: DE
          relationship: downstream
          description: "Hands off deliverables to DE for review"
      role_adoption_checklist:
        - "Verify access to required input sources"
        - "Review constraints and confirm compliance capability"
        - "Set up output templates and delivery channels"

Design Principles

• Role: Be specific about the domain. Avoid generic descriptions. Reference the FCC phase explicitly.
• Inputs: List concrete artifact types, not abstract concepts. Each input should be something a real person could hand you.
• Constraints: Use RFC 2119 language. Every "MUST" becomes a Tier 1 or Tier 2 constitution rule.
• Expected Output: List deliverables, not activities. Each output should be a tangible artifact.
• Archetype: Choose a metaphor that captures the persona's essence in two words.

---

Step 2: Create a Dimension Profile

The FCC dimension system defines 56 dimensions across 9 categories. Each persona gets a profile with ratings (typically 1--10) for each dimension.

Dimension Categories

Category	Dimensions	Example Dimensions
Core	7	expertise_depth, communication_clarity, adaptability
Behavioral	7	collaboration_preference, risk_tolerance, initiative_level
Communication	6	formality_level, documentation_preference, feedback_style
Cultural	6	diversity_awareness, ethical_sensitivity, global_perspective
Decision-Making	6	analytical_approach, consensus_seeking, speed_vs_accuracy
Professional	6	domain_specialization, continuous_learning, mentorship
Market	6	industry_awareness, competitive_analysis, trend_sensing
Innovative	6	creative_thinking, experimentation, disruption_tolerance
Advanced	6	systems_thinking, meta_cognition, emergence_sensitivity

Creating the Profile

Add dimension values to your persona YAML or create a separate dimensions file:

dimensions:
  MYP:
    core:
      expertise_depth: 8
      communication_clarity: 7
      adaptability: 6
    behavioral:
      collaboration_preference: 9
      risk_tolerance: 4
    # ... continue for all 56 dimensions

Tips for Calibration

• Use existing personas as reference points. If your persona is similar to BC, start with BC's profile and adjust.
• Extreme values (1 or 10) should be rare and justified by the persona's role.
• The Discernment Matrix (6 traits x 7 rating dimensions) provides additional behavioral calibration.

---

Step 3: Add Cross-Reference Matrix Entries

The cross-reference matrix defines how your persona interacts with other personas. Add entries to src/fcc/data/personas/cross_reference.yaml.

Entry Format

- source: MYP
  target: RC
  type: handoff          # One of: handoff, feedback, coordination, governance, champion-of
  direction: downstream  # downstream, upstream, or peer
  description: "MYP receives research inventory from RC to begin analysis"

- source: MYP
  target: DE
  type: handoff
  direction: upstream
  description: "MYP passes deliverables to DE for quality review"

- source: MYP
  target: BC
  type: coordination
  direction: peer
  description: "MYP and BC coordinate on design decisions"

Relationship Types

Type	When to Use
handoff	Your persona produces artifacts consumed by another, or receives artifacts from another
feedback	Your persona provides quality improvement feedback to another
coordination	Your persona works alongside another at the same level
governance	Your persona oversees or audits another
champion-of	Your persona orchestrates another (champion pattern only)

---

Step 4: Assign a Constitution

Constitutions define the rules your persona must follow, organized into three tiers.

Constitution Structure

constitutions:
  MYP:
    tier_1:  # Hard-stop: violation halts workflow immediately
      - "Never produce outputs without verifying input provenance"
      - "Never bypass quality validation before handoff"
    tier_2:  # Mandatory: violation requires documented exception
      - "All deliverables must include traceability references"
      - "All outputs must follow the organization's style guide"
    tier_3:  # Preferred: deviation is noted but allowed
      - "Include visual aids (diagrams, charts) where possible"
      - "Provide alternative recommendations alongside primary"

Add constitution rules to the constitution registry or to your plugin's governance data.

---

Step 5: Register as a Plugin (Optional)

If your persona lives outside the core src/fcc/ package, register it as a plugin.

Plugin Structure

fcc-my-personas/
  pyproject.toml
  src/
    fcc_my_personas/
      __init__.py
      plugin.py
      data/
        personas/
          my_personas.yaml

Plugin Implementation

from fcc.plugins.base import PersonaPlugin, PluginMeta, PluginType
from pathlib import Path

class MyPersonaPlugin(PersonaPlugin):
    def plugin_meta(self) -> PluginMeta:
        return PluginMeta(
            name="my-personas",
            version="1.0.0",
            plugin_type=PluginType.PERSONAS,
            description="Custom personas for my domain",
        )

    def personas_dir(self) -> Path:
        return Path(__file__).parent / "data" / "personas"

Registration in pyproject.toml

[project.entry-points."fcc.plugins.personas"]
my-personas = "fcc_my_personas.plugin:MyPersonaPlugin"

---

Step 6: Write Tests

Every custom persona needs tests that verify:

Required Tests

import pytest
from fcc.personas.registry import PersonaRegistry
from fcc._resources import get_personas_dir


def test_persona_loads():
    """Verify the persona loads without errors."""
    registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
    persona = registry.get("MYP")
    assert persona is not None
    assert persona.id == "MYP"
    assert persona.name == "My Persona"


def test_riscear_completeness():
    """Verify all 10 R.I.S.C.E.A.R. components are present."""
    registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
    persona = registry.get("MYP")
    riscear = persona.riscear

    assert riscear.role is not None and len(riscear.role) > 0
    assert riscear.inputs is not None and len(riscear.inputs) > 0
    assert riscear.style is not None and len(riscear.style) > 0
    assert riscear.constraints is not None and len(riscear.constraints) > 0
    assert riscear.expected_output is not None and len(riscear.expected_output) > 0
    assert riscear.archetype is not None and len(riscear.archetype) > 0
    assert riscear.responsibilities is not None and len(riscear.responsibilities) > 0
    assert riscear.role_skills is not None and len(riscear.role_skills) > 0
    assert riscear.role_collaborators is not None
    assert riscear.role_adoption_checklist is not None


def test_cross_references():
    """Verify cross-reference entries exist and reference valid personas."""
    registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
    persona = registry.get("MYP")
    for collab in persona.riscear.role_collaborators:
        assert registry.get(collab["persona_id"]) is not None


def test_persona_in_workflow():
    """Verify the persona can participate in a simulation."""
    from fcc.simulation.engine import SimulationEngine

    registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
    engine = SimulationEngine(registry=registry, mode="mock")
    # Run a minimal simulation including the custom persona
    trace = engine.run_single(persona_id="MYP", scenario_id="GEN-001")
    assert len(trace.steps) > 0

Testing Checklist

• Persona loads from YAML without errors
• All 10 R.I.S.C.E.A.R. components are non-empty
• Cross-reference entries reference valid persona IDs
• Persona appears in registry.by_category() results
• Persona can participate in mock simulations
• Persona's constitution rules are valid
• Dimension profile values are within valid ranges (1--10)
• make lint passes with the new YAML file
• make test passes with all new tests

---

Step 7: Generate Documentation

Use the DocGenerator to automatically generate documentation pages for your persona.

from fcc.scaffold.doc_generator import DocGenerator
from fcc.personas.registry import PersonaRegistry
from fcc._resources import get_personas_dir

registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
generator = DocGenerator(registry=registry, output_dir="docs/generated/")
generator.generate_persona("MYP")

This produces 56 files per persona, including:

• R.I.S.C.E.A.R. specification page
• Dimension profile page
• Cross-reference diagram
• Evolution guide
• Ecosystem prompt page
• Archetype interaction guide
• Tutorial pages (beginner through advanced)

You can also use the CLI:

fcc generate-docs --persona MYP --output-dir docs/generated/

---

Design Checklist Summary

Step	Action	Verification
1	R.I.S.C.E.A.R. YAML	All 10 components present and non-empty
2	Dimension profile	56 dimensions rated (1--10)
3	Cross-references	Upstream, downstream, and peer entries added
4	Constitution	Tier 1, 2, and 3 rules defined
5	Plugin registration	Entry point configured (if external)
6	Tests	All checklist items pass
7	Documentation	56 files generated without errors

---

Related Pages

• Plugin Development Guide -- detailed plugin system documentation
• Persona Comparison Guide -- when to use which persona
• R.I.S.C.E.A.R. Specification -- full specification reference
• Dimension System -- 56 dimensions across 9 categories
• Persona Ecosystem -- full persona catalog