Skip to content

Key Concepts

This page introduces the essential vocabulary of the FCC framework. Each concept is described briefly; for full definitions, see the Glossary.

FCC (Find, Create, Build, Critique, Ops)

The five-phase workflow cycle at the heart of the framework. Find handles research and discovery. Create handles drafting and assembly. Build handles engineering pipelines and infrastructure. Critique handles review and validation. Ops handles deployment and monitoring. The phases form a continuous loop where operational feedback flows back into the next round of research.

Personas

A persona is a specialized AI agent with a defined role, style, constraints, and expected outputs. FCC includes 102 core personas across 20 core categories plus 45 vertical personas across 6 vertical packs (healthcare, finance, legal, insurance, energy, government) plus 23 plugin personas. Core categories: core (5), integration (8), governance (4), stakeholder (5), champion (4), open_science, responsible_ai, jv_collaboration, docs_as_code, privacy, knowledge_graph, local_first_ai, data_engineering (6), ml_lifecycle (9), ml_models (11), devops (3), and app_development (2). Each persona is defined by a R.I.S.C.E.A.R. specification and loaded from YAML into the PersonaRegistry.

Champions

Champions are elevated personas that coordinate teams of base personas. Each champion has a champion_of link to a base persona and an orchestrates list of persona IDs it coordinates. For example, the Research Crafter Champion orchestrates the Research Crafter, the Catalog Indexer Architect, and the Research Inventory Crafter to produce a unified research package.

R.I.S.C.E.A.R. (10-Component Specification)

Every persona is defined by a R.I.S.C.E.A.R. specification with ten components: Role (what the persona does), Inputs (what it receives), Style (tone and format), Constraints (boundaries and rules), Expected Output (deliverables), Archetype (behavioral model), Responsibilities (ongoing duties), Role Skills (capabilities), Role Collaborators (interaction partners), and Role Adoption Checklist (readiness criteria).

Workflows

A workflow is a directed graph of persona nodes connected by edges. FCC provides six workflow graphs: a 5-node base sequence, a 20-node extended sequence, a 24-node complete graph, a 55-node extended_84 graph covering all personas, and two solution-level EAIFC graphs. Edges are typed as either handoff (work passes forward) or feedback (critique flows backward). The WorkflowGraph class supports topological ordering and BFS traversal.

Scenarios

A scenario defines the context for a simulation run: what documentation needs to be produced, what inputs are available, and what success criteria apply. FCC ships with six starter scenarios. Scenarios support dynamic validation against the persona registry using FCCValidator.from_registry.

Quality Gates

A quality gate is a named checkpoint with a threshold and a list of checks. FCC defines 25 quality gates across all persona categories. Each gate specifies the minimum conditions a persona's output must meet before it can be handed off. For example, the "Research Inventory Completeness" gate requires a capability matrix, annotated references, a traceability matrix, and capability tags.

Capability Tags

Capability tags are structured metadata labels that classify what each persona and workflow can do. FCC defines 30 tags organized by capability, category, and supercategory. Tags enable programmatic querying of the persona ecosystem -- for example, finding all personas in the governance-compliance category.

Discernment Matrix

The Discernment Matrix captures six behavioral traits for each persona: Humility, Professional Background, Curiosity, Taste, Inclusivity, and Responsibility. Each trait is rated across seven dimensions: self-rating, peer-rating, survey-rating, individual weighted rating, org-rating, external rating, and ranked percentile rating. The matrix enables nuanced persona profiling beyond role-based specifications.

Design Target Factors

Design Target Factors model six interpersonal qualities: Optimism, Social Connectivity, Influence, Diversity Appreciation, Curiosity, and Leadership. Like the Discernment Matrix, each factor uses the same seven rating dimensions. Together, the Discernment Matrix and Design Target Factors form the behavioral profile that distinguishes personas with similar roles but different working styles.

Persona Dimensions

The Persona Dimension system provides the deepest level of persona specification: 9 categories and 56 dimensions covering core persona elements, behavioral and motivational factors, communication and learning styles, cultural and social influences, decision-making and leadership approaches, professional development and wellness, market and regulatory awareness, innovative persona elements, and advanced persona attributes. Each dimension can have sub-attributes for fine-grained profiling.

Cross-Reference Matrix

The Cross-Reference Matrix is a queryable map of persona-to-persona interactions. It records who hands off to whom, who provides feedback to whom, and who coordinates with whom. The matrix supports queries by upstream, downstream, peers, and relationship type, enabling analysis of how information flows through the persona ecosystem.

Action Types

The 6-action-type system describes what a persona can do, orthogonal to workflows that describe when they act. The six types are: scaffold (generate new artifacts), refactor (improve existing artifacts), debug (diagnose and fix issues), test (validate quality), compare (evaluate alternatives), and document (generate documentation). The ActionEngine loads action definitions from YAML and executes them with persona-aware prompts.

Plugin System

FCC supports 10 plugin types discovered via Python entry points: personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, and subscribers. The PluginRegistry discovers installed plugins at runtime, validates them against their expected abstract base classes, and provides typed access. Plugins are registered in pyproject.toml under fcc.plugins.* entry-point groups.

Event Bus

The event bus is a thread-safe, in-process pub/sub system with 81 event types across 10 categories (workflow, node, persona, simulation, governance, deliverable, action, collaboration, plugin). Subscribers can register globally or with EventFilter to receive only specific event types, sources, or correlation IDs. The bus supports recording and replay for debugging and reproducible research.

Collaboration Engine

The collaboration engine enables human-in-the-loop workflows where AI agent personas and human reviewers take turns contributing to a deliverable. Sessions move through a lifecycle (created, active, completed, aborted) and include approval gates with scoring rubrics, handoff protocols to control agent autonomy, and a shared context for auditable key-value state.

Observability

The observability layer provides structured tracing and metrics collection using an OpenTelemetry-compatible span model with a built-in fallback. The FccTracer records nested spans with timing and attributes. FccMetrics collects counters and gauges for persona activations, gate results, AI calls, and action executions. Exporters output to the console or JSON files.

Dashboard

FCC includes terminal-based ASCII dashboards for monitoring the ecosystem, persona catalog, quality gate status, and collaboration sessions. Dashboards are accessed via the fcc dashboard CLI command and render using the _formatters and _widgets modules.

Constitution Registry

The constitution registry provides per-persona governance rules organized into three tiers: hard-stop rules that must never be violated, mandatory patterns that must be followed, and preferred conventions that should be followed when possible. Constitution rules are injected into action prompts automatically.

Next Steps