Downstream Adoption Guide

This guide is for senior engineers, architects, and tech leads responsible for integrating the FCC (Find-Create-Critique) Agent Team Framework into downstream ecosystem projects. It covers dependency management, API consumption, bridge patterns, documentation alignment, testing, and a step-by-step migration checklist.

---

1. What v1.0.0 Means for Downstream Projects

SemVer Guarantees

Starting with v1.0.0, the FCC framework provides strict Semantic Versioning 2.0.0 guarantees:

Release Type	Version Pattern	What Changes	Backward Compatible
Patch	1.0.x	Bug fixes only	Yes
Minor	1.x.0	New features, new symbols added	Yes
Major	2.0.0	Breaking changes (with migration guide)	No

All symbols exported from fcc.api.__all__ are covered by these guarantees for the entire 1.x release series. Internal modules (fcc.personas, fcc.workflow, etc.) retain their current signatures and will not change without notice in 1.x, but fcc.api is the contractual stable surface.

Public API Surface

The stable API namespace exports 24 public classes organized by domain:

Module	Exports	Purpose
fcc.api.personas	PersonaSpec, PersonaRegistry	Persona loading, querying, merging
fcc.api.workflow	WorkflowGraph, WorkflowAction, WorkflowActionRegistry, ActionEngine	Workflow execution and action management
fcc.api.simulation	AISimulationEngine, AIClient	Deterministic and AI-powered simulation
fcc.api.collaboration	CollaborationEngine, ScoringEngine	Human-in-the-loop sessions
fcc.api.evaluation	BenchmarkRunner, BenchmarkSuite, ModelCardGenerator	CLEAR+ benchmarks and model cards
fcc.api.compliance	ComplianceAuditor, RequirementRegistry, AIActClassifier, CompliancePipeline	EU AI Act and NIST AI RMF compliance
fcc.api.objectmodel	ModelFacade	Cross-project object model abstraction
fcc.api.messaging	EventBus, Event, EventType	Thread-safe pub/sub event system
fcc.api.search	SearchIndex, PersonaSearchIndex	Semantic search over personas and actions
fcc.api.knowledge	KnowledgeGraph	Knowledge graph construction and querying
fcc.api.rag	RAGPipeline, DocumentChunker	Retrieval-augmented generation

Import pattern for new code:

# Preferred: stable API namespace
from fcc.api import PersonaRegistry, EventBus, BenchmarkRunner

# Also works (will not break in 1.x):
from fcc.personas.registry import PersonaRegistry
from fcc.messaging.bus import EventBus
from fcc.evaluation.runner import BenchmarkRunner

What Does NOT Have SemVer Guarantees

• Modules under fcc.objectmodel.*_bridge (bridge adapters evolve with external projects)
• fcc.data file contents (YAML/JSON data files may gain new fields in minor releases)
• fcc.scaffold.cli command-line arguments (new flags may appear in minor releases)
• fcc.templates directory structure (template files may be reorganized)
• Test utilities and fixtures

---

2. Dependency Setup

Pinning FCC as a Dependency

Add FCC to your project's pyproject.toml with a version range that accepts minor/patch updates but blocks the next major:

[project]
dependencies = [
    "fcc-agent-team-ext>=1.0.0,<2.0.0",
]

Or in requirements.txt:

fcc-agent-team-ext>=1.0.0,<2.0.0

For development builds against a local checkout:

pip install -e /path/to/l2_fcc_agent_team_ext

Optional Dependency Groups

FCC provides granular optional dependency groups. Install only the extras your project needs:

Extra	Command	What It Adds
dev	pip install fcc-agent-team-ext[dev]	pytest, pytest-cov, ruff, build, twine
docs	pip install fcc-agent-team-ext[docs]	mkdocs, mkdocs-material, pymdown-extensions
observability	pip install fcc-agent-team-ext[observability]	opentelemetry-api, opentelemetry-sdk
notebooks	pip install fcc-agent-team-ext[notebooks]	jupyter, notebook, matplotlib, pandas
streamlit	pip install fcc-agent-team-ext[streamlit]	streamlit, plotly
cto	pip install fcc-agent-team-ext[cto]	cto>=6.0 (Converged Telecom Ontology)
protocols	pip install fcc-agent-team-ext[protocols]	websockets>=12.0
a2a	pip install fcc-agent-team-ext[a2a]	google-adk>=0.1.0 (Agent-to-Agent)
mcp	pip install fcc-agent-team-ext[mcp]	mcp>=1.0.0 (Model Context Protocol)
search	pip install fcc-agent-team-ext[search]	sentence-transformers, numpy
knowledge	pip install fcc-agent-team-ext[knowledge]	rdflib>=7.0
rag	pip install fcc-agent-team-ext[rag]	sentence-transformers, numpy
frontend	pip install fcc-agent-team-ext[frontend]	websockets>=12.0

Combine extras as needed:

pip install "fcc-agent-team-ext[cto,search,knowledge]>=1.0.0,<2.0.0"

Verifying Installation

import fcc
print(fcc.__version__)  # "1.0.1"

from fcc.api import PersonaRegistry
registry = PersonaRegistry.from_package_data()
print(f"Loaded {len(registry)} personas")  # 102 core + category-loaded

---

3. PAOM Integration

PAOM (Persona-as-Object Model) is the primary FCC consumer, operating as a Tier 2 project with SENTINEL routing, 13 plugin personas, and 25 MCP tools.

3.1 Importing the Persona Registry

Load the full persona catalog from FCC's packaged data:

from fcc.api import PersonaRegistry, PersonaSpec
from fcc._resources import get_data_dir

# Option A: Load from packaged data (all 102 core personas)
registry = PersonaRegistry.from_yaml_directory(get_data_dir() / "personas")

# Option B: Load and merge project-specific personas
shared = PersonaRegistry.from_yaml_directory(get_data_dir() / "personas")
local = PersonaRegistry.from_yaml("paom/custom_personas.yaml")
combined = shared.merge(local)

# Query by category
core_personas = combined.by_category("core")
governance_personas = combined.by_category("governance")

# Query champions
champions = combined.champions()
for champ in champions:
    print(f"{champ.id}: orchestrates {champ.orchestrates}")

3.2 Using R.I.S.C.E.A.R. Specifications

Every persona carries a 10-component R.I.S.C.E.A.R. specification. Access it through the riscear attribute:

persona = registry.get("RC")  # Research Curator

# Core R.I.S.C.E.A.R. components
print(persona.riscear.role)                 # Role description
print(persona.riscear.input)                # Expected input
print(persona.riscear.style)                # Communication style
print(persona.riscear.constraints)          # Operating constraints
print(persona.riscear.expected_output)      # Deliverables
print(persona.riscear.archetype)            # Behavioral archetype

# Extended R.I.S.C.E.A.R. components
print(persona.riscear.responsibilities)     # List of responsibilities
print(persona.riscear.role_skills)          # List of skills
print(persona.riscear.role_collaborators)   # List of collaborator IDs
print(persona.riscear.role_adoption_checklist)  # Adoption checklist items

Use R.I.S.C.E.A.R. data to drive PAOM's SENTINEL routing decisions:

def route_task_to_persona(task_description: str, registry: PersonaRegistry) -> PersonaSpec:
    """Route a task to the best-fit persona using R.I.S.C.E.A.R. skills."""
    best_match = None
    best_score = 0.0

    for persona in registry.all():
        # Score based on skill keyword overlap
        skills = persona.riscear.role_skills
        score = sum(
            1.0 for skill in skills
            if skill.lower() in task_description.lower()
        ) / max(len(skills), 1)

        if score > best_score:
            best_score = score
            best_match = persona

    return best_match

3.3 Consuming Generated Documentation

FCC generates documentation artifacts using Jinja2 templates. PAOM can consume these for persona-driven knowledge bases:

from fcc.scaffold.doc_generator import DocGenerator
from pathlib import Path

generator = DocGenerator(
    registry=registry,
    templates_dir=Path("custom/templates/") if Path("custom/templates/").exists() else None,
)

# Generate documentation for all personas
output_dir = Path("paom/generated-docs")
generator.generate(output_dir=output_dir)

# Generate for a specific persona
generator.generate_persona(persona_id="RC", output_dir=output_dir)

3.4 Plugin Development Pattern

PAOM provides 13 plugin personas to FCC via the fcc.plugins.personas entry point. To register a PAOM plugin:

Step 1: Create a plugin module

# paom/fcc_plugin.py
from fcc.personas.models import PersonaSpec

def get_personas() -> list[PersonaSpec]:
    """Return PAOM's plugin personas for FCC registration."""
    return [
        PersonaSpec.from_dict({
            "id": "SNTR",
            "name": "SENTINEL Router",
            "fcc_phase": "Find",
            "category": "integration",
            "riscear": {
                "role": "Routes tasks to appropriate personas using LLM-powered intent classification.",
                "input": "Raw user requests or task descriptions.",
                "style": "Concise routing decisions with confidence scores.",
                "constraints": "Must route within 500ms. Never fabricate persona capabilities.",
                "expected_output": "Routing decision with persona ID, confidence, and reasoning.",
                "archetype": "The Air Traffic Controller",
                "responsibilities": ["Intent classification", "Persona selection", "Confidence scoring"],
                "role_skills": ["NLP routing", "Intent detection", "Load balancing"],
                "role_collaborators": ["RC", "BC", "DE"],
                "role_adoption_checklist": ["Configure routing thresholds", "Map task categories"],
            },
        }),
        # ... additional PAOM personas
    ]

Step 2: Register in pyproject.toml

[project.entry-points."fcc.plugins.personas"]
paom = "paom.fcc_plugin:get_personas"

Step 3: Verify registration

fcc plugins list
# Should show: paom (personas) - 13 personas registered

---

4. AOME Integration

AOME (Adaptive Object Model Extension) is a Tier 1 project providing a privacy taxonomy with 1,026 nodes. It integrates with FCC through the object model bridge layer and 67 vocabulary mappings.

4.1 The AOME Bridge

FCC provides a clean-room bridge adapter at src/fcc/objectmodel/aome_bridge.py. The bridge follows the Protocol-Dataclass-Adapter-Sentinel pattern:

from fcc.objectmodel.aome_bridge import aome_available, AOMEFacadeAdapter

# Guard with sentinel before importing AOME
if aome_available():
    from aome.core.model import AOMEModel

    model = AOMEModel(version="0.1.0")
    facade = AOMEFacadeAdapter(model)

    # Standard ModelFacade interface
    print(facade.name)                        # "AOME"
    print(facade.version)                     # "0.1.0"
    print(facade.stats())                     # {"phrases": N, "categories": N, ...}

    # Search across privacy taxonomy
    results = facade.search("consent", limit=20)

    # Access wrapped repositories
    phrases_repo = facade.get_repository("phrases")
    if phrases_repo:
        print(f"Total phrases: {phrases_repo.count()}")
else:
    # Degrade gracefully when AOME is not installed
    from fcc.objectmodel.examples import create_sample_model
    facade = create_sample_model()

4.2 CTO-AOME Vocabulary Mappings (67 Mappings)

The file src/fcc/data/objectmodel/cto_aome_element_mapping.yaml defines 67 cross-vocabulary mappings between CTO elements and AOME phrases across 7 domains:

Domain	Mapping Count	CTO Subject Area	AOME Category	Example Mapping
Party/Customer	14	Party	party_management	CustomerAccount.account_id -> account_id
Product/Service	12	Product	product_catalog	ProductSpecification.spec_id -> product_spec_id
Resource	10	Resource	resource_management	PhysicalResource.resource_id -> resource_id
Location	6	Common	location	GeographicAddress.street -> street_address
Order/Agreement	9	Party	order_management	CustomerOrder.order_id -> order_id
Billing/Finance	8	Common	billing	BillingAccount.billing_id -> billing_account_id
Common	8	Common	common	BaseEntity.created_date -> created_date

Load and query these mappings programmatically:

from fcc.objectmodel.mapping import VocabularyMapping
from fcc._resources import get_data_dir
import yaml

# Load CTO-AOME element mapping
mapping_path = get_data_dir() / "objectmodel" / "cto_aome_element_mapping.yaml"
with open(mapping_path) as f:
    raw = yaml.safe_load(f)

mappings = [
    VocabularyMapping(
        source_id=f"cto:{m['cto_concept_name']}.{m['cto_element_name']}",
        source_name=m["cto_element_name"],
        source_vocabulary="cto",
        target_id=f"aome:{m['aome_category']}.{m['aome_phrase_name']}",
        target_name=m["aome_phrase_name"],
        target_vocabulary="aome",
        similarity_score=m["similarity_score"],
    )
    for m in raw["mappings"]
]

# Filter by domain
party_mappings = [m for m in mappings if "party" in m.target_id.lower()]
print(f"Party domain: {len(party_mappings)} mappings")

# Find high-confidence exact matches
exact = [m for m in mappings if m.similarity_score >= 0.95]
print(f"Exact matches (>=0.95): {len(exact)}")

# Flag items needing review
review_needed = [m for m in mappings if m.requires_review]
print(f"Requires review (<0.75): {len(review_needed)}")

4.3 Unified Facade for Cross-Model Queries

The unified_model_config.yaml configures a federated query layer that searches across CTO, AOME, CONSTEL, and FCC models in parallel:

from fcc.objectmodel.facade import ModelFacade
from fcc.objectmodel.cto_bridge import cto_available, CTOFacadeAdapter
from fcc.objectmodel.aome_bridge import aome_available, AOMEFacadeAdapter

# Build a multi-facade query dispatcher
facades: dict[str, ModelFacade] = {}

if cto_available():
    from cto.core.model import CTOModel
    facades["cto"] = CTOFacadeAdapter(CTOModel(version="6.1.0"))

if aome_available():
    from aome.core.model import AOMEModel
    facades["aome"] = AOMEFacadeAdapter(AOMEModel(version="0.1.0"))

# Federated search across all available models
def federated_search(query: str, limit: int = 20) -> dict[str, list]:
    """Search across all registered model facades."""
    results = {}
    for name, facade in facades.items():
        results[name] = facade.search(query, limit=limit)
    return results

# Example: find "customer" across CTO and AOME
hits = federated_search("customer")
for model_name, entities in hits.items():
    print(f"{model_name}: {len(entities)} results")

4.4 Writing Your Own AOME-Side Adapter

If you maintain the AOME project and want to bridge it back to FCC, follow the adapter template:

# In your AOME project: aome/fcc_adapter.py
from typing import Any

def adapt_aome_phrase_to_fcc_entity(phrase: Any) -> dict:
    """Convert an AOME phrase to an FCC-compatible entity dict."""
    return {
        "id": f"aome:{phrase.id}",
        "name": phrase.name,
        "category": phrase.category.name if phrase.category else "uncategorized",
        "vocabulary": "aome",
        "risk_level": getattr(phrase, "risk_level", "unknown"),
        "metadata": phrase.to_dict() if hasattr(phrase, "to_dict") else {},
    }

---

5. CONSTEL Integration

CONSTEL (Convergent Semantic Topology) is a Tier 1 project managing TMF SID metadata with knowledge graph federation. It integrates through 45 SID-CTO mappings and 26 eTOM business process definitions.

5.1 The CONSTEL Bridge

from fcc.objectmodel.constel_bridge import constel_available, CONSTELFacadeAdapter

if constel_available():
    from constel.core.model import ConstelModel

    model = ConstelModel(version="0.2.0")
    facade = CONSTELFacadeAdapter(model)

    # Standard ModelFacade interface
    print(facade.name)                        # "CONSTEL"
    print(facade.stats())                     # {"namespaces": N, "nodes": N, "edges": N, "triples": N}

    # Per-namespace statistics
    ns_stats = facade.namespace_stats()
    for ns, counts in ns_stats.items():
        print(f"  {ns}: {counts}")

    # Search across all namespace graphs
    results = facade.search("Customer", limit=10)

    # Access a specific namespace graph
    abe_repo = facade.get_repository("ABE")
    if abe_repo:
        print(f"ABE entities: {abe_repo.count()}")

    # Get full entity with connected edges
    entity = facade.get_full("customer-001")
    if entity:
        print(f"Node: {entity['node']}")
        print(f"Connected edges: {len(entity['edges'])}")

5.2 SID-CTO Mappings (45 Mappings)

The file src/fcc/data/objectmodel/constel_cto_sid_mapping.yaml defines 45 cross-vocabulary mappings between CONSTEL TMF SID entities and CTO concepts, covering three TMF namespaces:

Namespace	Description	Mapping Count	CTO Subject Areas
ABE	Aggregate Business Entities -- core SID domain entities	25	Party, Product, Resource, Service, Common
BP	Business Processes -- eTOM process decomposition	12	Mapped via related_cto_concepts
FUNCTION	Business Functions -- operational capabilities	8	Resource, Service, Common

Example mapping entries:

CONSTEL Entity	Namespace	CTO Concept	CTO Subject Area	Confidence
Customer	ABE	Customer	Party	0.96
CustomerAccount	ABE	CustomerAccount	Party	0.95
Party	ABE	Party	Party	0.97
ProductSpecification	ABE	ProductSpecification	Product	0.93
PhysicalResource	ABE	PhysicalResource	Resource	0.94

Load and query SID mappings:

from fcc._resources import get_data_dir
import yaml

# Load SID-CTO mapping
sid_path = get_data_dir() / "objectmodel" / "constel_cto_sid_mapping.yaml"
with open(sid_path) as f:
    sid_data = yaml.safe_load(f)

# Index by namespace
by_namespace: dict[str, list] = {}
for mapping in sid_data["mappings"]:
    ns = mapping["constel_namespace"]
    by_namespace.setdefault(ns, []).append(mapping)

for ns, entries in by_namespace.items():
    high_conf = [e for e in entries if e["confidence"] >= 0.90]
    print(f"{ns}: {len(entries)} total, {len(high_conf)} high-confidence (>=0.90)")

5.3 eTOM Business Processes (26 Processes)

The file src/fcc/data/objectmodel/constel_business_processes.yaml defines 26 eTOM business process entities organized across three levels:

eTOM Level	Description	Count	Example Processes
Level 1	Strategic and high-level operational groupings	6	Strategy & Commit, Infrastructure Lifecycle Management, Product Lifecycle Management
Level 2	Functional domain groupings within Level 1	10	Customer Relationship Management, Service Configuration & Activation, Revenue Assurance
Level 3	Specific executable business processes	10	Order Handling, Problem Management, Bill Calculation

Each process declares its relationships to CTO concepts and CONSTEL namespaces:

from fcc._resources import get_data_dir
import yaml

bp_path = get_data_dir() / "objectmodel" / "constel_business_processes.yaml"
with open(bp_path) as f:
    bp_data = yaml.safe_load(f)

for process in bp_data["processes"]:
    print(f"[L{process['etom_level']}] {process['process_name']}")
    print(f"  Domain: {process['etom_domain']}")
    print(f"  CTO concepts: {', '.join(process['related_cto_concepts'])}")
    print(f"  Namespaces: {', '.join(process['related_constel_namespaces'])}")

5.4 Knowledge Graph Federation

CONSTEL's knowledge graphs can be federated with FCC's knowledge graph layer. Build a combined graph across both projects:

from fcc.api import KnowledgeGraph
from fcc.knowledge.builders import build_full_fcc_graph
from fcc.api import PersonaRegistry

# Build FCC's knowledge graph
registry = PersonaRegistry.from_package_data()
fcc_kg = build_full_fcc_graph(registry)

print(f"FCC KG: {fcc_kg.node_count} nodes, {fcc_kg.edge_count} edges")

# If CONSTEL is available, build a federated view
from fcc.objectmodel.constel_bridge import constel_available

if constel_available():
    facade = CONSTELFacadeAdapter(ConstelModel(version="0.2.0"))

    # Query CONSTEL for entities that overlap with FCC concepts
    sid_entities = facade.search("Party", limit=50)
    for entity in sid_entities:
        print(f"  SID: {getattr(entity, 'label', entity)}")

For full federation with namespace resolution, use the federation registry:

from fcc.federation.namespaces import NamespaceRegistry, NamespaceConfig

ns_registry = NamespaceRegistry()

# Register FCC namespace
ns_registry.register(NamespaceConfig(
    namespace="fcc",
    prefix="fcc",
    base_uri="https://fcc.example.org/entities/",
    version="1.0.0",
    description="FCC Agent Team Framework",
))

# Register CONSTEL namespace
ns_registry.register(NamespaceConfig(
    namespace="tmf",
    prefix="tmf",
    base_uri="https://constel.example.org/sid/",
    version="0.2.0",
    description="CONSTEL TMF SID",
))

# Resolve cross-namespace URIs
fcc_uri = ns_registry.resolve_uri("fcc", "persona/RC")
tmf_uri = ns_registry.resolve_uri("tmf", "abe/Customer")
print(f"FCC: {fcc_uri}")   # https://fcc.example.org/entities/persona/RC
print(f"TMF: {tmf_uri}")   # https://constel.example.org/sid/abe/Customer

5.5 Exporting to RDF/OWL/JSON-LD

CONSTEL's TMF knowledge graphs can be exported using FCC's serializers for interoperability with triple stores:

from fcc.knowledge.serializers import JSONLDSerializer, RDFSerializer
from fcc.knowledge.builders import build_full_fcc_graph

registry = PersonaRegistry.from_package_data()
kg = build_full_fcc_graph(registry)

# Export to JSON-LD (for Neo4j, MongoDB, or web APIs)
jsonld = JSONLDSerializer().serialize(kg)

# Export to RDF Turtle (for Apache Jena, Stardog, or Virtuoso)
rdf = RDFSerializer().serialize(kg, format="turtle")

---

6. Documentation Restructuring Checklist

When adopting FCC v1.0.0, downstream projects should align their documentation infrastructure to consume FCC's canonical definitions consistently.

6.1 Update Persona References to FCC v1.0.0 IDs

FCC v1.0.0 defines 102 core personas with stable two-to-four character IDs across 20 categories. Downstream projects must use these canonical IDs, not project-local aliases.

Core persona categories and ID ranges:

Category	Persona Count	Example IDs	Purpose
core	5	RC, BC, DE, RB, UG	Find-Create-Critique baseline
integration	8	CIA, STE, TS, RML, SMC, SCP, CO, RS	Cross-system integration
governance	4	DGS, PTE, AMS, GCA	Quality and compliance
stakeholder	5	EC, IAF, LDA, UMC, BI	Business stakeholder support
champion	4	RCHM, BCHM, UGCH, RBCH	Team coordination
data_engineering	6	--	Data pipeline personas
ml_lifecycle	9	--	ML workflow personas
ml_models	11	--	Model management personas
devops	3	--	Infrastructure personas
protocol_engineering	6	--	Protocol design personas
ux_visualization	6	--	UX and D3.js personas
jv_governance	6	--	Joint venture governance

Action required in your project:

1. Search your codebase for hard-coded persona references.
2. Replace any custom or legacy IDs with canonical FCC IDs.
3. Use PersonaRegistry.get(id) for all persona lookups rather than string matching.

# Bad: hard-coded string matching
if persona_name == "Research Curator":
    ...

# Good: canonical ID lookup
persona = registry.get("RC")
if persona is not None:
    ...

6.2 Align Documentation with R.I.S.C.E.A.R. Terminology

All persona documentation should use the 10-component R.I.S.C.E.A.R. naming convention. Update existing docs to use these standard section headings:

Component	Section Heading	Content
R -- Role	"Role"	What the persona does and why it exists
I -- Input	"Input"	What data/artifacts the persona receives
S -- Style	"Style"	Communication tone and format preferences
C -- Constraints	"Constraints"	Boundaries, limitations, and rules
E -- Expected Output	"Expected Output"	Deliverables and artifact specifications
A -- Archetype	"Archetype"	Behavioral metaphor (e.g., "The Librarian")
R -- Responsibilities	"Responsibilities"	Enumerated duty list
Role Skills	"Skills"	Capability keywords for routing
Role Collaborators	"Collaborators"	Upstream and downstream persona IDs
Role Adoption Checklist	"Adoption Checklist"	Steps to activate the persona

6.3 Set Up Docs-as-Code Generation Consuming FCC Templates

FCC ships 23 Jinja2 templates for docs-as-code generation. Configure your project to consume them:

from fcc.scaffold.doc_generator import DocGenerator
from fcc.api import PersonaRegistry
from fcc._resources import get_data_dir, get_templates_dir
from pathlib import Path

# Load personas (shared + project-specific)
registry = PersonaRegistry.from_yaml_directory(get_data_dir() / "personas")

# Option 1: Use FCC's built-in templates
generator = DocGenerator(registry=registry)

# Option 2: Override with project-specific templates
generator = DocGenerator(
    registry=registry,
    templates_dir=Path("my_project/templates/docs/"),
)

# Generate full documentation suite
generator.generate(output_dir=Path("docs/generated/"))

Add generation to your CI pipeline:

# .github/workflows/fcc-docs.yml
- name: Generate FCC docs
  run: |
    fcc generate-docs --output-dir ./docs/generated
    fcc validate-docs --input-dir ./docs/generated
    fcc sitemap --output-dir ./docs/generated

6.4 Integrate with FCC's MkDocs Site Structure

FCC uses MkDocs Material for its documentation site. Downstream projects can extend or mirror this structure:

# mkdocs.yml in your downstream project
site_name: "My Project Documentation"
theme:
  name: material

nav:
  - Home: index.md
  - Getting Started:
    - Installation: getting-started/installation.md
    - Quick Start: getting-started/quick-start.md
  - FCC Integration:
    - Personas: fcc/personas.md      # Generated from FCC
    - Workflows: fcc/workflows.md    # Generated from FCC
    - Governance: fcc/governance.md  # Generated from FCC
  - API Reference: api/index.md

plugins:
  - search

Install FCC's docs dependencies:

pip install "fcc-agent-team-ext[docs]>=1.0.0,<2.0.0"

---

7. Testing Integration Points

7.1 Verify Persona Loading

The most fundamental integration test confirms that your project can load the FCC persona registry:

def test_fcc_persona_registry_loads():
    """Verify FCC persona registry loads successfully."""
    from fcc.api import PersonaRegistry

    registry = PersonaRegistry.from_package_data()

    assert len(registry) >= 102, f"Expected 102+ personas, got {len(registry)}"
    assert registry.get("RC") is not None, "Research Curator must exist"
    assert registry.get("BC") is not None, "Blueprint Crafter must exist"
    assert registry.get("DE") is not None, "Documentation Evangelist must exist"

7.2 Verify Bridge Availability

Test that optional bridges degrade gracefully:

import pytest

def test_cto_bridge_graceful_degradation():
    """CTO bridge works when available, degrades when not."""
    from fcc.objectmodel.cto_bridge import cto_available

    if cto_available():
        from fcc.objectmodel.cto_bridge import CTOFacadeAdapter
        # Adapter class should be importable and instantiable
        assert CTOFacadeAdapter is not None
    else:
        # Should not raise -- just returns False
        assert cto_available() is False

def test_aome_bridge_graceful_degradation():
    """AOME bridge works when available, degrades when not."""
    from fcc.objectmodel.aome_bridge import aome_available

    if aome_available():
        from fcc.objectmodel.aome_bridge import AOMEFacadeAdapter
        assert AOMEFacadeAdapter is not None
    else:
        assert aome_available() is False

def test_constel_bridge_graceful_degradation():
    """CONSTEL bridge works when available, degrades when not."""
    from fcc.objectmodel.constel_bridge import constel_available

    if constel_available():
        from fcc.objectmodel.constel_bridge import CONSTELFacadeAdapter
        assert CONSTELFacadeAdapter is not None
    else:
        assert constel_available() is False

7.3 Verify Vocabulary Mappings Load

def test_cto_aome_mappings_load():
    """Verify CTO-AOME vocabulary mapping file parses correctly."""
    from fcc._resources import get_data_dir
    import yaml

    path = get_data_dir() / "objectmodel" / "cto_aome_element_mapping.yaml"
    with open(path) as f:
        data = yaml.safe_load(f)

    assert "mappings" in data
    assert len(data["mappings"]) == 67, f"Expected 67 mappings, got {len(data['mappings'])}"

    for mapping in data["mappings"]:
        assert "cto_element_name" in mapping
        assert "aome_phrase_name" in mapping
        assert 0.0 <= mapping["similarity_score"] <= 1.0

def test_constel_sid_mappings_load():
    """Verify CONSTEL SID-CTO mapping file parses correctly."""
    from fcc._resources import get_data_dir
    import yaml

    path = get_data_dir() / "objectmodel" / "constel_cto_sid_mapping.yaml"
    with open(path) as f:
        data = yaml.safe_load(f)

    assert "mappings" in data
    assert len(data["mappings"]) == 45, f"Expected 45 mappings, got {len(data['mappings'])}"

    for mapping in data["mappings"]:
        assert "constel_entity" in mapping
        assert "cto_concept_name" in mapping
        assert 0.0 <= mapping["confidence"] <= 1.0

def test_constel_business_processes_load():
    """Verify CONSTEL business processes file parses correctly."""
    from fcc._resources import get_data_dir
    import yaml

    path = get_data_dir() / "objectmodel" / "constel_business_processes.yaml"
    with open(path) as f:
        data = yaml.safe_load(f)

    assert "processes" in data
    assert len(data["processes"]) == 26, f"Expected 26 processes, got {len(data['processes'])}"

7.4 Verify Event Bus Integration

def test_event_bus_integration():
    """Verify EventBus can publish and receive events."""
    from fcc.api import EventBus, Event, EventType

    bus = EventBus()
    received = []

    def handler(event: Event) -> None:
        received.append(event)

    bus.subscribe(EventType.SIMULATION_STARTED, handler)
    bus.publish(Event(event_type=EventType.SIMULATION_STARTED, data={"test": True}))

    assert len(received) == 1
    assert received[0].data["test"] is True

7.5 Verify Workflow Action Execution

def test_action_engine_runs():
    """Verify ActionEngine executes a persona action."""
    from fcc.api import PersonaRegistry, WorkflowActionRegistry, ActionEngine
    from fcc.workflow.actions import WorkflowActionType
    from fcc._resources import get_data_dir

    data_dir = get_data_dir()
    persona_reg = PersonaRegistry.from_yaml_directory(data_dir / "personas")
    action_reg = WorkflowActionRegistry.from_yaml_directory(
        data_dir / "personas" / "actions"
    )

    engine = ActionEngine(persona_reg, action_reg)
    result = engine.run("RC", WorkflowActionType.SCAFFOLD)

    assert result.success
    assert result.content is not None

7.6 CI Integration Template

Add these tests to your downstream project's CI:

# .github/workflows/fcc-integration.yml
name: FCC Integration Tests
on: [push, pull_request]

jobs:
  integration:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install project with FCC
        run: pip install -e ".[dev]"

      - name: Run FCC integration tests
        run: pytest tests/fcc_integration/ -v --tb=short

      - name: Validate FCC project structure
        run: fcc validate

      - name: Run API audit
        run: fcc api audit

---

8. Migration Checklist Template

Copy the following checklist into your project's issue tracker or MIGRATION.md to track FCC v1.0.0 adoption progress.

# FCC v1.0.0 Adoption Checklist

## Phase 1: Dependency Setup
- [ ] Add `fcc-agent-team-ext>=1.0.0,<2.0.0` to project dependencies
- [ ] Install required optional extras (cto, search, knowledge, etc.)
- [ ] Verify `import fcc; print(fcc.__version__)` returns `1.0.x`
- [ ] Migrate imports from `fcc.personas.registry` to `fcc.api` namespace
- [ ] Run `fcc api audit` and resolve any warnings

## Phase 2: Persona Alignment
- [ ] Audit all hard-coded persona references in project codebase
- [ ] Replace custom/legacy persona IDs with canonical FCC IDs
- [ ] Update persona documentation to use R.I.S.C.E.A.R. section headings
- [ ] Verify persona loading: `PersonaRegistry.from_package_data()` >= 102
- [ ] If applicable, register project-specific plugin personas via entry points
- [ ] Run `fcc validate` to confirm persona YAML compliance

## Phase 3: Object Model Bridge Integration
- [ ] Identify which bridges apply (CTO, AOME, CONSTEL)
- [ ] Implement sentinel guard pattern for optional bridge imports
- [ ] Verify vocabulary mapping files load without errors
- [ ] Write integration tests for each bridge with graceful degradation
- [ ] Assess object model evolution stage using `ObjectModelAssessment`
- [ ] Document integration depth in project architecture docs

## Phase 4: Documentation Infrastructure
- [ ] Set up FCC docs-as-code generation in CI pipeline
- [ ] Configure `DocGenerator` with project-specific template overrides
- [ ] Add `fcc generate-docs` and `fcc validate-docs` to CI workflow
- [ ] Generate MkDocs sitemap with `fcc sitemap`
- [ ] Integrate generated docs into project MkDocs/Sphinx nav structure
- [ ] Verify all generated docs render correctly in docs site

## Phase 5: Event Bus and Observability
- [ ] Subscribe to FCC EventBus for relevant event types
- [ ] Configure event forwarding to project's observability platform
- [ ] Set up OpenTelemetry integration if using OTel (optional)
- [ ] Verify events flow end-to-end in staging environment

## Phase 6: Compliance and Governance
- [ ] Run `fcc compliance-audit` against project personas
- [ ] Review EU AI Act risk classifications for project-relevant personas
- [ ] Configure quality gate thresholds for project requirements
- [ ] Set up governance persona roles (DGS, PTE, AMS, GCA)
- [ ] Generate model cards with `fcc model-card` for project personas
- [ ] Archive compliance audit reports in project governance directory

## Phase 7: Knowledge Federation (if applicable)
- [ ] Register project namespace in FCC NamespaceRegistry
- [ ] Build FCC knowledge graph from persona registry
- [ ] Export knowledge graph to target format (JSON-LD, RDF, SKOS)
- [ ] If federated: configure cross-namespace entity resolution
- [ ] Verify cross-project vocabulary coverage with `assess_cross_project()`

## Phase 8: Testing and Validation
- [ ] Write FCC integration test suite (persona, bridge, mapping, event bus)
- [ ] Add integration tests to CI pipeline
- [ ] Run CLEAR+ benchmarks against project-specific scenarios
- [ ] Verify all FCC-dependent tests pass in clean environment
- [ ] Document any FCC API usage patterns in project developer guide

## Phase 9: Plugin Registration (if applicable)
- [ ] Implement plugin module (personas, engines, templates, etc.)
- [ ] Register entry points in pyproject.toml under `fcc.plugins.*`
- [ ] Verify plugin loads with `fcc plugins list`
- [ ] Run `fcc plugins validate` to confirm plugin compliance
- [ ] Declare cross-plugin dependencies in ecosystem YAML if applicable
- [ ] Map cross-plugin persona interactions

## Phase 10: Production Readiness
- [ ] Full test suite passes (project + FCC integration)
- [ ] Documentation site builds and deploys with FCC-generated content
- [ ] Monitoring dashboards show FCC event flow
- [ ] Team trained on FCC workflows (Week 1-3 adoption plan complete)
- [ ] First FCC-driven simulation executed on real project content
- [ ] Adoption metrics baselined (quality gate pass rate, cycle time)

---

Appendix A: Ecosystem Project Registry

The canonical ecosystem project registry lives at src/fcc/data/ecosystem/project_registry.yaml. Below is a summary:

Project	FCC Tier	Version	Role	Key Integration Points
FCC Agent Team Ext	Authority	v1.0.1	Canonical FCC/R.I.S.C.E.A.R. authority	--
PAOM	Tier 2 (Active)	v3.0.0	SENTINEL routing, 13 plugin personas	25 MCP tools, A2A Agent Card
AOME	Tier 1 (Strict)	v0.1.0	Privacy taxonomy (1,026 nodes), 5 plugin personas	9 MCP tools, 67 CTO mappings
CONSTEL	Tier 1 (Strict)	v0.2.0	TMF metadata (UCM), 5 plugin personas	45 SID mappings, 26 eTOM processes
CTO	Tier 3 (Minimal)	v6.1.0	Telecom ontology (1,520 concepts)	Object model foundation
Sky-Parlour	Tier 1 (Strict)	PI 1	D3.js visualization, 218 workflows	React 18 frontend
AI-COE-Docs	Tier 2 (Active)	--	Patent evaluation, open science	141 FCC artifacts
Distiller (Fornax)	Tier 2 (Active)	--	Vocabulary distillation	Cross-vocab mappings
Research Center	Tier 3 (Minimal)	v0.1.0	Statistical foundation	4 MCP tools
p1	Tier 4 (None)	--	Event capture	OTel integration only
L2 Distro Hub	Tier 4 (None)	--	Release distribution	No FCC integration

Adoption Tier Definitions

Tier	Name	FCC Requirement	Example
1	Strict	Pre-commit validation, mandatory persona compliance	CONSTEL, AOME, Sky-Parlour
2	Active	Active persona usage, partial enforcement	PAOM, AI-COE-Docs, Distiller
3	Minimal	Reference only, optional integration	Research Center, CTO
4	None	No FCC integration, autonomous governance	p1, L2 Distro Hub

---

Appendix B: Plugin Entry Point Reference

FCC supports 10 plugin types, each registered through a separate entry point group:

Plugin Type	Entry Point Group	What It Provides
Personas	fcc.plugins.personas	Additional persona specifications
Engines	fcc.plugins.engines	Custom simulation engines
Templates	fcc.plugins.templates	Jinja2 doc templates
Scorers	fcc.plugins.scorers	Deliverable quality scorers
Validators	fcc.plugins.validators	Custom validation rules
Providers	fcc.plugins.providers	Data/model providers
Governance	fcc.plugins.governance	Governance policy plugins
Scenarios	fcc.plugins.scenarios	Custom simulation scenarios
Workflows	fcc.plugins.workflows	Custom workflow graphs
Subscribers	fcc.plugins.subscribers	EventBus subscriber plugins

Register plugins in your pyproject.toml:

[project.entry-points."fcc.plugins.personas"]
my_project = "my_project.fcc_personas:get_personas"

[project.entry-points."fcc.plugins.subscribers"]
my_project = "my_project.fcc_events:get_subscribers"

---

Appendix C: Key File Reference

File	Purpose
src/fcc/api/__init__.py	Stable API surface (24 public symbols)
src/fcc/_resources.py	Centralized resource path resolution
src/fcc/objectmodel/base.py	DomainEntity, RepositoryProtocol protocols
src/fcc/objectmodel/facade.py	ModelFacade ABC
src/fcc/objectmodel/mapping.py	VocabularyMapping, MappingStore protocol
src/fcc/objectmodel/cto_bridge.py	CTO adapter (canonical bridge pattern)
src/fcc/objectmodel/aome_bridge.py	AOME adapter
src/fcc/objectmodel/constel_bridge.py	CONSTEL adapter
src/fcc/data/objectmodel/cto_aome_element_mapping.yaml	67 CTO-AOME vocabulary mappings
src/fcc/data/objectmodel/constel_cto_sid_mapping.yaml	45 SID-CTO concept mappings
src/fcc/data/objectmodel/constel_business_processes.yaml	26 eTOM business process definitions
src/fcc/data/objectmodel/unified_model_config.yaml	Unified model federation configuration
src/fcc/federation/namespaces.py	NamespaceRegistry, NamespaceConfig
src/fcc/knowledge/builders.py	Knowledge graph builder functions
src/fcc/knowledge/serializers.py	OWL/RDF/SKOS/JSON-LD serializers
src/fcc/plugins/orchestration.py	CrossPluginOrchestrator
MIGRATION_0x_to_1x.md	Full migration guide from v0.x to v1.0.0

---

Related Resources

• Migration Guide: v0.x to v1.0.0 -- Upgrade steps and new APIs
• Ecosystem Integration Guide -- Deep-dive on clean-room adapter pattern
• Team Adoption Guide -- Three-week onboarding plan
• Scaling FCC Across Projects -- Multi-project deployment patterns
• Integration Guide -- CI/CD, observability, and toolchain integration
• Plugin Development Guide -- Building custom plugins
• Custom Persona Design Guide -- Creating new personas