Chapter 14: Appendices¶

Appendix A: Glossary¶

Term	Definition
Action Engine	Component that executes workflow actions and generates prompts for each action type
Adoption Checklist	R.I.S.C.E.A.R. component listing steps to onboard a persona
AOME	Adaptive Object Model Engine — provides privacy taxonomy and adaptive data models
Approval Gate	Checkpoint in a collaboration session requiring a minimum quality score to pass
Archetype	R.I.S.C.E.A.R. component identifying the persona's behavioral archetype
Champion Persona	Elevated persona that coordinates a team of base personas via `champion_of` and `orchestrates`
Collaboration Engine	System managing human-agent collaboration sessions, turns, gates, and scoring
CONSTEL	Constellation Metadata Service — provides vocabulary and metadata services
Constitution	Set of governance rules (hard-stop, mandatory, preferred) for a persona
ConstitutionRegistry	Centralized lookup for per-persona constitutions
Cross-Reference Matrix	Queryable map of persona-to-persona interactions (upstream, downstream, peers)
CTO Bridge	Three-layer architecture connecting FCC to enterprise ontology systems
Design Target Factors	6 factors (Optimism, Social Connectivity, Influence, etc.) rated across 7 dimensions
Dimension Profile	Collection of dimension attributes characterizing a persona
Discernment Matrix	6 traits (Humility, Curiosity, Taste, etc.) rated across 7 dimensions
Event Bus	Thread-safe in-process pub/sub system with 81 event types
EventSubscriberPlugin	Plugin type that reacts to events on the event bus
FCC	Find-Create-Critique — the core workflow cycle
Frozen Dataclass	Python dataclass with `frozen=True` ensuring immutability
Governance Plugin	Plugin that extends constitutions, quality gates, or compliance checks
HandoffProtocol	Rules for turn-taking between humans and agents in collaboration sessions
Hard-Stop Rule	Tier-1 constitution rule that blocks workflow execution on violation
HITL	Human-in-the-Loop — design pattern requiring human review at critical points
Mandatory Pattern	Tier-2 constitution rule that must be followed (waivable with justification)
Mock Simulation	Deterministic simulation mode using predefined responses (no AI calls)
PAOM	Persona-Aware Object Model — consumes FCC personas for LLM routing
Persona	An agent archetype defined by a R.I.S.C.E.A.R. specification
PersonaRegistry	Central store for loading, querying, and merging persona definitions
Plugin	Extension point (10 types: personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, subscribers)
Preferred Pattern	Tier-3 constitution rule representing a recommended best practice
ProgressTracker	Component tracking completion state (steps, percentage, status)
Quality Gate	Defined quality bar for a persona's deliverables with threshold and checks
QualityScore	Score (1-5) with rubric breakdown, justification, and timestamp
R.I.S.C.E.A.R.	Role, Input, Style, Constraints, Expected Output, Archetype, Responsibilities, Role Skills, Role Collaborators, Role Adoption Checklist
ScoringEngine	Component that evaluates deliverable quality against rubrics and gates
SessionRecorder	Persists collaboration sessions to JSON and replays them via event bus
SharedContext	Auditable key-value workspace shared across collaboration session turns
Simulation Engine	Runs FCC workflows in deterministic (mock) or AI-powered modes
Tag	Structured label with capability, category, and supercategory dimensions
Trace	Record of a simulation run containing steps, events, and timing data
Workflow Action	One of 6 action types: scaffold, refactor, debug, test, compare, document
Workflow Graph	Directed graph of nodes and edges representing an FCC workflow

Appendix B: Persona Quick Reference¶

Core Personas (5)¶

ID	Name	Phase	Archetype
RC	Research Crafter	Find	Knowledge Synthesizer
BC	Blueprint Crafter	Create	Systems Architect
DE	Documentation Evangelist	Critique	Quality Guardian
RB	Runbook Crafter	Build	Operations Specialist
UG	User Guide Crafter	Build	Communication Bridge

Integration Specialists (8)¶

ID	Name	Phase
CIA	Catalog Indexer Architect	Create
UMC	UI Mockup Crafter	Create
STE	Semantic Taxonomy Engineer	Find
TS	Traceability Specialist	Critique
BV	Blueprint Validator	Critique
RIC	Research Inventory Crafter	Find
GCA	Governance Compliance Auditor	Critique
SCMS	Supply Chain Mapping Spec.	Find

Governance Personas (4)¶

ID	Name	Phase
DGS	Data Governance Specialist	Critique
PTE	Privacy Taxonomy Engineer	Find
ERO	Ethics Review Officer	Critique
CRO	Compliance & Regulatory Officer	Critique

Stakeholder Hub (5)¶

ID	Name	Phase
SA	Stakeholder Analyst	Find
SM	Stakeholder Manager	Ops
BE	Business Evangelist	Create
CL	Change Leader	Ops
VDA	Value Delivery Analyst	Critique

Champions (4)¶

ID	Name	Orchestrates
CH-RC	Research Champion	Find-phase personas
CH-BC	Blueprint Champion	Create-phase personas
CH-DE	Documentation Champion	Critique-phase personas
CH-OPS	Operations Champion	Build/Ops personas

Plugin Personas (23)¶

Plugin personas span 12 categories: 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). See src/fcc/data/personas/ for full definitions.

Total: 102 core + 45 vertical + 23 plugin = 170 personas

Appendix C: CLI Reference¶

`fcc init`¶

Initialize a new FCC project.

fcc init --name "my-project" --dir ./my-project

Option	Required	Default	Description
`--name`	Yes	—	Project name
`--dir`	No	`.`	Target directory

`fcc add-persona`¶

Add a persona to an existing project.

fcc add-persona "Test Specialist" --phase Critique --id TST --dir .

Option	Required	Description
`NAME`	Yes	Persona name (positional)
`--phase`	Yes	Phase: Find, Create, Build, Critique, Ops
`--id`	Yes	Short ID (e.g., TST)
`--dir`	No	Project directory (default `.`)

`fcc validate`¶

Validate project structure and persona schemas.

fcc validate --dir .

`fcc generate-docs`¶

Generate documentation for all personas.

fcc generate-docs --dir . --output-dir ./docs

`fcc validate-docs`¶

Validate generated documentation completeness.

fcc validate-docs --dir ./docs

`fcc sitemap`¶

Generate a documentation sitemap.

fcc sitemap --dir ./docs --output sitemap.yaml

`fcc collab`¶

Manage collaboration sessions.

fcc collab start --workflow base_5 --participants human-alice,RC,BC
fcc collab status --session-id <id>
fcc collab complete --session-id <id>

`fcc dashboard`¶

Launch terminal dashboards.

fcc dashboard ecosystem    # Ecosystem project overview
fcc dashboard personas     # Persona catalog
fcc dashboard quality      # Quality gate status
fcc dashboard collab       # Collaboration session status

Appendix D: YAML Schema Reference¶

Persona Schema (Key Fields)¶

- id: string          # Unique 2-4 character ID
  name: string        # Human-readable name
  phase: string       # Find | Create | Build | Critique | Ops
  category: string    # core | integration | governance | ...
  champion_of: string # (optional) Category this persona champions
  orchestrates: list   # (optional) List of persona IDs this champion coordinates
  riscear:
    role: string
    input: string
    style: string
    constraints: string
    expected_output: string
    archetype: string
    responsibilities: list[string]
    role_skills: list[string]
    role_collaborators: list[string]
    adoption_checklist: list[string]
  doc_context:          # (optional) Documentation generation context
    primary_action: string
    primary_output: string
    constitution:
      hard_stop: list[string]
      mandatory: list[string]
      preferred: list[string]

Workflow Schema (Key Fields)¶

{
  "id": "string",
  "name": "string",
  "nodes": [
    {
      "id": "string",
      "label": "string",
      "phase": "string",
      "persona_ids": ["string"]
    }
  ],
  "edges": [
    {
      "source": "string",
      "target": "string"
    }
  ]
}

Event Schema (Key Fields)¶

event_type: string    # One of 25 EventType values
timestamp: string     # ISO 8601 UTC
source: string        # Emitting component
data: object          # Event-specific payload

Quality Gate Schema¶

quality_gates:
  - id: string         # e.g., QG-RC-001
    name: string       # Human-readable name
    persona_id: string # Target persona or ALL
    threshold: float   # 0.0 to 1.0
    checks: list       # List of check identifiers

Appendix E: Environment Setup Guide¶

Prerequisites¶

Python 3.11 or later
make (GNU Make)
Git

Installation¶

# Clone the repository
git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

# Create virtual environment
make venv
source .venv/bin/activate

# Install with development dependencies
make install-dev

Verify Installation¶

# Check version
fcc --version

# Run tests
make test

# Run linter
make lint

Dependencies¶

Category	Packages
Core	pyyaml, jsonschema, click, jinja2, python-dotenv
AI	anthropic, openai
Optional	opentelemetry-api, opentelemetry-sdk
Dev	pytest, pytest-cov, ruff

Project Structure¶

After cloning, the key directories are:

src/fcc/           # Package source code
src/fcc/data/      # Package data (YAML, JSON, schemas)
tests/             # Test suite
docs/guidebook/    # This guidebook

Troubleshooting¶

Issue	Solution
`ModuleNotFoundError: fcc`	Run `pip install -e .` from the project root
Schema validation errors	Run `fcc validate` to identify schema mismatches
Missing data files	Ensure `make install-dev` completed successfully
Test failures	Check Python version (requires 3.11+)

Key Takeaways

The glossary defines 30+ terms used throughout the guidebook.

The persona quick reference covers all 102 core and 23 plugin personas.

CLI commands are available via fcc --help for up-to-date usage.

YAML schemas are defined in src/fcc/data/schemas/ with JSON Schema validation.

Environment setup requires Python 3.11+, make, and git.