Managing a Plugin Ecosystem¶

As FCC deployments grow, you will manage multiple plugins, each contributing personas, workflows, or governance rules. The EcosystemRegistry tracks projects and their port allocations, while the PluginRegistry and CrossPluginOrchestrator handle discovery, validation, and coordination. This tutorial covers ecosystem management at scale.

The Ecosystem Registry¶

The EcosystemRegistry maintains a catalog of all projects in your FCC ecosystem. Each project has metadata including its FCC adoption tier, maturity level, dependencies, and port allocations:

from fcc.ecosystem.registry import EcosystemRegistry, EcosystemProject

# Load the ecosystem from YAML
# registry = EcosystemRegistry.from_yaml("ecosystem.yaml")

# Or build programmatically
projects = [
    EcosystemProject(
        id="fcc-core",
        name="FCC Agent Team Extension",
        fcc_adoption_tier="authority",
        maturity_level="production",
        description="Core FCC framework with 147 personas (102 core + 45 vertical)",
        repo_url="https://github.com/org/fcc-core",
        test_count=1971,
        port_allocations=(
            {"port": 8100, "service": "docs-server", "protocol": "http"},
            {"port": 8101, "service": "api", "protocol": "http"},
        ),
    ),
    EcosystemProject(
        id="paom",
        name="PAOM Analysis Platform",
        fcc_adoption_tier="consumer",
        maturity_level="beta",
        description="Persona-Archetype Ontological Mapper",
        test_count=850,
        dependencies=("fcc-core",),
        port_allocations=(
            {"port": 8200, "service": "api", "protocol": "http"},
            {"port": 8201, "service": "dashboard", "protocol": "http"},
        ),
    ),
    EcosystemProject(
        id="constel",
        name="CONSTEL Taxonomy Engine",
        fcc_adoption_tier="consumer",
        maturity_level="alpha",
        description="Constellation-based taxonomy management",
        test_count=420,
        dependencies=("fcc-core",),
        port_allocations=(
            {"port": 3400, "service": "api", "protocol": "http"},
        ),
    ),
]

registry = EcosystemRegistry(projects)
print(f"Total projects: {len(registry)}")

Querying by Adoption Tier¶

FCC defines four adoption tiers that indicate a project's relationship to the framework:

Tier	Description
`authority`	Owns and defines FCC specifications
`producer`	Extends FCC with plugins and integrations
`consumer`	Uses FCC personas, workflows, or governance
`observer`	Monitors or reports on FCC ecosystem activity

# Find all consumer projects
consumers = registry.by_tier("consumer")
for project in consumers:
    print(f"  {project.id}: {project.name} ({project.maturity_level})")

# Find production-ready projects
production = registry.by_maturity("production")
for project in production:
    print(f"  {project.id}: {project.test_count} tests")

Port Allocation Management¶

As ecosystem projects proliferate, port conflicts become a real risk. The registry provides tools to detect and resolve them:

# List all port allocations across the ecosystem
all_ports = registry.all_ports()
for alloc in all_ports:
    print(f"  Port {alloc.port}: {alloc.project_id} ({alloc.service})")

# Detect conflicts
conflicts = registry.port_conflicts()
if conflicts:
    for conflict in conflicts:
        print(f"  Port {conflict['port']} claimed by: {conflict['projects']}")
else:
    print("No port conflicts detected")

Expected output:

  Port 8100: fcc-core (docs-server)
  Port 8101: fcc-core (api)
  Port 8200: paom (api)
  Port 8201: paom (dashboard)
  Port 3400: constel (api)
No port conflicts detected

Combining Plugin Discovery with Ecosystem Tracking¶

Use the PluginRegistry to discover installed plugins, then cross-reference with the ecosystem registry:

from fcc.plugins.registry import PluginRegistry

plugin_reg = PluginRegistry()
result = plugin_reg.discover()

print(f"Plugins discovered: {result.discovered}")
print(f"Plugins loaded: {result.loaded}")

# Cross-reference: which ecosystem projects have installed plugins?
for project in registry:
    project_plugins = [
        meta for meta in plugin_reg.get_all_meta()
        if meta.source_package == project.id
    ]
    if project_plugins:
        print(f"\n{project.name}:")
        for meta in project_plugins:
            print(f"  {meta.name} v{meta.version} ({meta.plugin_type.value})")

Dependency Validation¶

The CrossPluginOrchestrator validates that plugin dependencies are satisfied:

from fcc.plugins.orchestration import (
    CrossPluginOrchestrator,
    PluginDependency,
    PluginHealthStatus,
)

# Define ecosystem dependencies
dependencies = [
    PluginDependency(
        source_plugin="paom",
        target_plugin="fcc-core",
        dependency_type="provides_metadata",
        description="PAOM reads FCC persona specifications",
    ),
    PluginDependency(
        source_plugin="constel",
        target_plugin="fcc-core",
        dependency_type="provides_metadata",
        description="CONSTEL reads FCC dimension profiles",
    ),
]

orchestrator = CrossPluginOrchestrator(dependencies=dependencies)

# Check what each project depends on
for project in registry:
    deps = orchestrator.resolve_dependencies(project.id)
    if deps:
        targets = [d.target_plugin for d in deps]
        print(f"{project.id} depends on: {', '.join(targets)}")

# Check what depends on fcc-core
reverse = orchestrator.reverse_dependencies("fcc-core")
print(f"\nProjects depending on fcc-core: {len(reverse)}")
for dep in reverse:
    print(f"  {dep.source_plugin}: {dep.description}")

Ecosystem Health Monitoring¶

Aggregate health data from all projects into a single report:

# Simulate health checks
statuses = []
for project in registry:
    statuses.append(PluginHealthStatus(
        plugin_id=project.id,
        healthy=project.maturity_level != "alpha",
        persona_count=84 if project.id == "fcc-core" else 12,
        error="Pre-release: not yet stable" if project.maturity_level == "alpha" else None,
    ))

report = orchestrator.check_health(statuses)
print(f"\nEcosystem Health Report")
print(f"  Total plugins: {report.total_plugins}")
print(f"  Healthy: {report.healthy_plugins}")
print(f"  Unhealthy: {report.unhealthy_plugins}")
print(f"  Total personas: {report.total_personas}")

Persisting Ecosystem Configuration¶

Save the ecosystem as YAML for version control:

import yaml

ecosystem_data = {
    "projects": [project.to_dict() for project in registry]
}

with open("ecosystem.yaml", "w") as f:
    yaml.dump(ecosystem_data, f, default_flow_style=False, sort_keys=False)

# Reload
loaded_registry = EcosystemRegistry.from_yaml("ecosystem.yaml")
print(f"Loaded {len(loaded_registry)} projects")

CLI Dashboard Integration¶

FCC includes terminal dashboards for ecosystem monitoring:

# View ecosystem overview
fcc dashboard ecosystem

# View persona catalog
fcc dashboard personas

# View quality gate status
fcc dashboard quality

These dashboards read from the ecosystem registry and plugin registry to display real-time status using ASCII formatting.

Best Practices¶

Ecosystem Management

Assign port ranges by project (e.g., 8100-8199 for fcc-core, 8200-8299 for PAOM) to prevent conflicts.
Version your ecosystem YAML alongside your code to track project additions and tier changes over time.
Run health checks in CI to catch dependency and port conflicts before deployment.
Use adoption tiers to communicate each project's relationship to the FCC specification clearly.

Next Steps¶

Building Your First FCC Plugin -- Create a plugin package
Cross-Plugin Orchestration -- Dependency and interaction management
Adding Observability to Workflows -- Monitor ecosystem health with metrics