PersonaSpec Hierarchy¶

The FCC framework centralises every agent definition behind a single frozen dataclass, PersonaSpec, declared in src/fcc/personas/models.py:168. A persona composes its ten-component R.I.S.C.E.A.R. contract (RISCEARSpec, line 104), a six-trait discernment matrix, six design-target factors, and an optional dimension profile spanning 56 attributes. The structure is deliberately flat and frozen so that personas can be loaded from YAML, diffed, serialised, and cross-referenced without accidental mutation. This diagram exposes the aggregation relationships that connect those components and distinguishes core personas from champion personas via the champion_of and orchestrates fields.

The diagram below details the composition of PersonaSpec and the value objects it aggregates.

classDiagram
    class PersonaSpec {
        <<frozen dataclass>>
        +id : str
        +name : str
        +fcc_phase : str
        +role_title : str
        +color : str
        +category : str
        +champion_of : str | None
        +orchestrates : list[str]
        +doc_context : dict | None
    }

    class RISCEARSpec {
        <<frozen dataclass>>
        +role : str
        +inputs : list[str]
        +style : str
        +constraints : list[str]
        +expected_output : str
        +archetype : str
        +responsibilities : list[str]
        +role_skills : list[str]
        +role_collaborators : list[str]
        +role_adoption_checklist : list[str]
    }

    class DiscernmentTrait {
        <<frozen dataclass>>
        +trait : str
        +ratings : dict
    }

    class DesignTargetFactor {
        <<frozen dataclass>>
        +factor : str
        +ratings : dict
    }

    class PersonaDimensionProfile {
        <<frozen dataclass>>
        +dimensions : list
    }

    class Deliverable {
        <<frozen dataclass>>
        +name : str
        +description : str
    }

    class CollaborationLink {
        <<frozen dataclass>>
        +persona_id : str
        +relationship : str
    }

    PersonaSpec "1" *-- "1" RISCEARSpec : riscear
    PersonaSpec "1" *-- "6" DiscernmentTrait : discernment_matrix
    PersonaSpec "1" *-- "6" DesignTargetFactor : design_target_factors
    PersonaSpec "1" o-- "0..1" PersonaDimensionProfile : dimension_profile
    PersonaSpec "1" *-- "1..*" Deliverable : deliverables
    PersonaSpec "1" *-- "1..*" CollaborationLink : collaboration
    PersonaSpec "1" ..> "0..1" PersonaSpec : champion_of
    PersonaSpec "1" ..> "0..*" PersonaSpec : orchestrates

This structure is the right one to reach for whenever a new agent archetype needs to be added — subclassing is unnecessary because the category field plus the champion pointers provide all the variation the registry needs. The tradeoff is that validation has to be performed at load time (via JSON schema and FCCValidator) rather than at construction, since frozen dataclasses accept any typed payload. Extension points are the doc_context dict and PersonaDimensionProfile, both optional, which allow downstream consumers to attach ecosystem-specific metadata without forking the model.

The flat composition also keeps serialisation symmetrical: a YAML round-trip through PersonaRegistry produces byte-identical output, which in turn keeps the docs-as-code generator deterministic and the model-card pipeline idempotent.

Key contracts¶

PersonaSpec — the top-level frozen dataclass holding identity, category, champion pointers, and aggregates over the full R.I.S.C.E.A.R. contract plus the discernment and design-target matrices.
RISCEARSpec — the ten-component role specification (Role, Input, Style, Constraints, Expected Output, Archetype, Responsibilities, Role Skills, Role Collaborators, Role Adoption Checklist).
DiscernmentTrait — one of six traits (Humility, Professional Background, Curiosity, Taste, Inclusivity, Responsibility) rated across seven dimensions.
DesignTargetFactor — one of six factors (Optimism, Social Connectivity, Influence, Diversity Appreciation, Curiosity, Leadership) with per-dimension ratings.
PersonaDimensionProfile — optional aggregation over the 56 persona dimensions (9 categories) for richer matching and search.
Deliverable — a named artefact the persona is expected to produce.
CollaborationLink — a typed edge to a peer persona that participates in the role's collaborators set.

PersonaSpec Hierarchy¶

Key contracts¶

See also¶