Glossary¶

A complete reference of terms used throughout the FCC Agent Team Framework.

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

The five-phase workflow cycle that organizes all documentation work in the framework. The Find phase covers research and discovery. The Create phase covers drafting and assembly of documentation artifacts. The Build phase covers engineering pipelines and infrastructure automation. The Critique phase covers review, validation, and quality assurance. The Ops phase covers deployment, monitoring, and operational maintenance. Feedback from later phases flows back into Find, forming a continuous improvement loop.

R.I.S.C.E.A.R.¶

The 10-component specification that defines every persona in the framework. The acronym stands for Role, Inputs, Style, Constraints, Expected Output, Archetype, and Responsibilities. The specification is extended with three additional components: Role Skills, Role Collaborators, and Role Adoption Checklist. Implemented as the RISCEARSpec dataclass in src/fcc/personas/models.py.

PersonaSpec¶

The complete specification for an FCC persona. A PersonaSpec contains an ID, name, FCC phase assignment, role title, R.I.S.C.E.A.R. specification, deliverables, collaboration links, category assignment, Discernment Matrix traits, Design Target Factors, dimension profile, and champion metadata. Defined as a frozen dataclass and loaded from YAML.

PersonaRegistry¶

The in-memory registry that loads, stores, and queries personas. Supports loading from a single YAML file, multiple files, or an entire directory. Provides lookup by ID, name, phase, or category, as well as champion-specific queries. The registry merges dimension profiles from a dimensions/ subdirectory when loading from a directory.

WorkflowGraph¶

A directed graph of persona nodes connected by typed edges. FCC provides three workflow graphs: a 5-node base sequence (core personas), a 20-node extended sequence (core, integration, and governance personas), and a 24-node complete graph (all personas). Supports topological ordering, BFS traversal, and adjacency queries. Edges are typed as handoff (forward flow) or feedback (backward flow).

SimulationEngine¶

The engine that executes FCC workflows by traversing a WorkflowGraph and invoking personas at each node. FCC provides two modes: deterministic (mock), which generates repeatable traces without calling external APIs, and AI-powered, which invokes language model APIs (Anthropic or OpenAI) with persona-aware system prompts. Implemented as AISimulationEngine in src/fcc/simulation/ai_engine.py.

ScenarioLoader¶

The component that loads scenario definitions from YAML files and validates them against the persona registry. A scenario specifies what documentation needs to be produced, what inputs are available, and what success criteria apply. FCC ships with six starter scenarios. Dynamic validation uses FCCValidator.from_registry to ensure scenarios reference valid persona IDs.

QualityGate¶

A named checkpoint that defines the minimum conditions a persona's output must meet before handoff. Each quality gate has an ID, a name, a persona assignment, a threshold (0.0 to 1.0), and a list of checks. FCC defines 25 quality gates across all persona categories. Quality gates are defined in data/governance/quality_gates.yaml.

CapabilityTag¶

A structured metadata label that classifies what a persona or workflow can do. Each tag has three levels: capability (the specific function), category (the functional group), and supercategory (the strategic alignment). FCC defines 30 capability tags in data/governance/tag_registry.yaml. Tags enable programmatic discovery and filtering of personas.

Champion¶

An elevated persona that coordinates a team of base personas. Each champion has a champion_of field linking it to a base persona and an orchestrates list of persona IDs it coordinates. The four champions are: Research Crafter Champion (RCHM), Blueprint Crafter Champion (BCHM), User Guide Crafter Champion (UGCH), and Runbook Crafter Champion (RBCH). Champions produce unified packages that aggregate output from their orchestrated teams.

CrossReferenceMatrix¶

A queryable map of persona-to-persona interactions. Each entry records a source persona, a target persona, a relationship type (handoff, feedback, coordination, governance, or champion-of), an interaction description, and a strength level (primary or secondary). The matrix supports queries by upstream, downstream, peers, and relationship type. Can be auto-generated from persona collaboration links or loaded from YAML.

DimensionProfile¶

The deepest level of persona specification, organized into 9 categories and 56 dimensions. Categories include: Core Persona Elements (7), Behavioral and Motivational Factors (6), Communication and Learning Styles (4), Cultural and Social Influences (4), Decision-Making and Leadership Approaches (5), Professional Development and Wellness (5), Market and Regulatory Awareness (5), Innovative Persona Elements (10), and Advanced Persona Attributes (10). Implemented as PersonaDimensionProfile in src/fcc/personas/dimensions.py.

DiscernmentMatrix¶

A behavioral profiling model that captures six traits per 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 differentiation of personas that share similar roles but have distinct behavioral profiles.

DesignTargetFactors¶

A complementary behavioral model that captures six interpersonal qualities per persona: Optimism, Social Connectivity, Influence, Appreciation for Diversity, Curiosity, and Leadership. Each factor uses the same seven rating dimensions as the Discernment Matrix. Together with the Discernment Matrix, the Design Target Factors form the complete behavioral profile for each persona.

DocGenerator¶

The docs-as-code generation engine that produces documentation files from persona specifications using Jinja2 templates. A full generation run produces up to 1,348 files: 504 tutorials, 504 prompts, and 144 workflows, plus cross-reference pages and a sitemap. The generator supports filtering by persona ID or category. Implemented in src/fcc/scaffold/doc_generator.py.

WorkflowActionType¶

The six action types a persona can perform: scaffold (generate new artifacts), refactor (improve existing artifacts), debug (diagnose and fix issues), test (validate quality), compare (evaluate alternatives), and document (generate documentation). Defined as the WorkflowActionType enum in src/fcc/workflow/actions.py.

WorkflowAction¶

A single action definition for a persona. Describes what a persona does when performing a specific action type, including execution steps, required inputs, expected outputs, and constraints. Defined as a frozen dataclass and loaded from YAML.

WorkflowActionRegistry¶

Registry of workflow actions that provides lookup by persona ID, action type, or both. Loaded from YAML files in data/personas/actions/. Supports loading from a single file, a directory, or with JSON Schema validation.

ActionEngine¶

The engine that executes persona workflow actions. Combines a PersonaRegistry, a WorkflowActionRegistry, and an optional AI client to produce ActionResult instances. In mock mode, returns deterministic results. In AI mode, builds persona-aware prompts from R.I.S.C.E.A.R. specifications and action definitions.

ActionResult¶

The output of running an action via ActionEngine.run(). Contains the persona ID, action type, generated content, success status, optional error message, and metadata (including mode: mock or ai).

EventBus¶

A thread-safe, in-process pub/sub system for FCC workflow events. Supports global and filtered subscriptions, event recording, and history retrieval. Not a singleton -- each test or engine can create its own instance. Implemented in src/fcc/messaging/bus.py.

Event¶

An immutable event in the FCC messaging system. Contains an event ID (UUID), event type, ISO 8601 timestamp, source component, payload dictionary, and optional correlation ID. Defined as a frozen dataclass in src/fcc/messaging/events.py.

EventType¶

Enumeration of 81 event types across 10 categories: workflow, node, persona, simulation, governance, deliverable, action, collaboration, plugin, protocol, budget, and messaging. Each type uses a dotted string format (e.g., workflow.started, action.completed).

EventFilter¶

A filter for selecting which events a subscriber receives. Supports filtering by event types, source components, and correlation IDs. Multiple criteria are combined with AND logic. Used with EventBus.subscribe().

Subscriber¶

A callable that receives an Event and performs some action (logging, analysis, state update). Subscribers are registered with the EventBus and invoked synchronously when matching events are published. Type alias for Callable[[Event], Any].

EventSerializer¶

Serialization utility for events. Converts events to/from JSON strings, handles batch operations, and supports saving to / loading from JSON files. Used for event persistence and replay.

EventReplay¶

Replays recorded events through an EventBus. Supports replaying from a list of events or from a file, with optional filtering by correlation ID or source. Useful for testing, debugging, and reproducible research.

EventSubscriberPlugin¶

The 10th plugin type in the FCC framework. An abstract base class for plugins that contribute event subscribers to the EventBus. Plugins implementing this ABC register event handlers that are automatically wired when the plugin is discovered. Defined in src/fcc/messaging/plugin_bridge.py.

PluginType¶

Enumeration of 10 plugin types: personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, and subscribers. Each type maps to a fcc.plugins.* entry-point group.

PluginMeta¶

Metadata for a discovered plugin. Contains ID, name, version, plugin type, description, author, source package, and tags. Required for all plugins and returned by the plugin_meta() method.

PluginRegistry¶

Central registry for FCC plugins discovered via setuptools entry points. Scans all fcc.plugins.* entry-point groups, instantiates plugins, validates them against their expected ABCs, and provides typed access. Implemented in src/fcc/plugins/registry.py.

CrossPluginOrchestrator¶

Orchestrates interactions between ecosystem plugins. Manages plugin dependencies, cross-plugin persona interaction matrices, and ecosystem health monitoring. Supports dependency resolution, reverse dependency queries, and interaction validation.

PluginDependency¶

A dependency between two plugins, specifying the source plugin, target plugin, dependency type (e.g., provides_llm, provides_taxonomy, provides_metadata), and description.

PluginInteraction¶

An interaction between personas from different plugins. Records source and target personas with their respective plugins, interaction type (upstream, downstream, peer), and description.

CollaborationEngine¶

Runtime engine for human-agent collaboration sessions. Manages session lifecycle (create, start, take turns, evaluate gates, complete/abort), scoring, handoff detection, and event publication. Implemented in src/fcc/collaboration/engine.py.

CollaborationSession¶

A frozen snapshot of a collaboration session. Contains session ID, workflow ID, status, participants, ordered turns, approval gates, handoff protocol, shared context, and timestamps. Produced by CollaborationEngine methods.

SessionTurn¶

An individual turn in a collaboration session. Records the turn ID, type (human, agent, system), actor, content, optional approval decision, optional score, and timestamp.

ApprovalGate¶

A checkpoint in a collaboration session where a deliverable is scored against a rubric. Specifies the gate ID, linked workflow node, required minimum score, whether human approval is required, and rubric criteria.

ApprovalDecision¶

The outcome of evaluating a deliverable at an approval gate: approved, rejected, needs_revision, or deferred.

HandoffProtocol¶

Rules governing turn-taking in a collaboration session. Specifies max_consecutive_agent_turns (default 3), auto_approve_threshold (score above which human approval is auto-granted), and escalation_threshold (score below which escalation to human is required).

ScoringEngine¶

Evaluates deliverable quality against rubrics and approval gates. Maintains scoring history and computes per-persona capability ratings. The decision logic is: score >= required_score yields APPROVED; score >= required_score - 1.0 yields NEEDS_REVISION; below that yields REJECTED.

QualityScore¶

A quality score assigned to a deliverable, containing the score ID, deliverable ID, scorer, numeric score (1-5), per-rubric-item scores, justification text, and timestamp.

AgentCapabilityRating¶

A derived rating computed from a persona's approval and quality history. Includes total approvals, total rejections, average quality score, total evaluations, approval rate, and an effective rating combining both metrics.

SharedContext¶

An auditable key-value store shared across all turns in a collaboration session. Tracks the full change history with actor attribution, timestamps, and old/new values for every mutation.

ProgressTracker¶

Tracks completion progress for entities such as sessions and workflows. Supports registering entities with a total step count, advancing progress, and querying completion percentages. Provides a summary view across all tracked entities.

SessionRecorder¶

Saves and loads collaboration sessions to/from JSON files. Supports replaying session turns as events through an EventBus for analysis and testing.

FccTracer¶

Tracer for FCC operations using an OpenTelemetry-compatible span model. Creates nested spans as context managers with timing, attributes, and status tracking. Falls back to an internal implementation when OTel is not installed. Implemented in src/fcc/observability/tracing.py.

SpanData¶

A frozen snapshot of a recorded span. Contains span ID, trace ID, parent span ID, name, start/end times, status (ok/error), and arbitrary attributes. Supports duration calculation.

SpanContext¶

A mutable span context used during span execution. Provides set_attribute() and set_status() methods. The end() method produces a frozen SpanData snapshot.

FccMetrics¶

Metrics collector for FCC operations. Records counter increments and gauge observations with labels. Provides 7 pre-defined metrics: simulation step, persona activation, gate result, deliverable created, AI call, AI latency, and action execution. Supports querying by name and computing totals.

MetricPoint¶

A single metric data point with a name, numeric value, metric type (counter, gauge, histogram), key-value labels, and ISO 8601 timestamp.

SpanExporter / MetricExporter¶

Abstract base classes for exporting spans and metrics. FCC provides four built-in exporters: ConsoleSpanExporter, JsonFileSpanExporter, ConsoleMetricExporter, and JsonFileMetricExporter.

EcosystemRegistry¶

Registry of ecosystem projects loaded from YAML. Tracks project metadata including FCC adoption tier, maturity level, dependencies, port allocations, and test counts. Supports querying by tier, maturity level, and detecting port conflicts.

EcosystemProject¶

An ecosystem project with metadata: ID, name, FCC adoption tier (authority, producer, consumer, observer), maturity level, description, repository URL, port allocations, dependencies, and test count.

PortAllocation¶

A port allocation for a project service, specifying port number, project ID, service name, protocol, status, and notes. Used by EcosystemRegistry.all_ports() to detect port conflicts across the ecosystem.

ConstitutionRegistry¶

Per-persona constitution lookup providing 3-tier governance rules: hard-stop (absolute prohibitions), mandatory (required patterns), and preferred (recommended conventions). Constitution rules are automatically injected into action prompts by the ActionEngine.

Dashboard¶

Terminal-based ASCII dashboards for monitoring the FCC ecosystem. Five dashboard types: ecosystem (project overview), simulation (progress tracking), personas (catalog browser), quality (gate status), and collaboration (session monitoring). Accessed via fcc dashboard <type>.

traced¶

A decorator for automatically tracing function calls. The decorated function must accept a tracer keyword argument of type FccTracer. If tracer is None, the function runs without tracing overhead. Defined in src/fcc/observability/tracing.py.