Skip to content

Workflow Graphs

The FCC framework defines 3 workflow graphs of increasing complexity: a 5-node base graph, a 20-node extended graph, and a 24-node complete graph with Champion orchestration. Each graph is stored as JSON under data/workflows/ and loaded by the WorkflowGraph class in src/fcc/workflow/graph.py.

flowchart LR
    RC[RC: Research Crafter] -->|handoff| BC[BC: Blueprint Crafter]
    BC -->|handoff| DE[DE: Documentation Evangelist]
    DE -->|handoff| RB[RB: Runbook Crafter]
    DE -->|handoff| UG[UG: User Guide Crafter]
    RB -.->|feedback| BC
    UG -.->|feedback| BC
    UG -.->|feedback| RC
    RB -.->|feedback| RC

Graph Structure

Every workflow graph consists of:

  • Nodes -- Personas, each with an id, name, and type (either persona or champion).
  • Edges -- Directed connections between personas, each with a from, to, label, and type.
  • Meta -- An id, title, and description for the graph itself.

Edge Types

Type Description Traversal
handoff A forward-flowing delivery of artifacts from one persona to another. Handoffs define the primary work pipeline. Included in topological sort
feedback A backward-flowing return of critique, corrections, or improvements. Feedback edges create cycles that the topological sort excludes. Excluded from topological sort, included in BFS
orchestration A Champion directing a base persona. Orchestration edges are structurally handoff-type but semantically represent coordination rather than artifact delivery. Included in topological sort

Base Graph (5 Nodes)

The canonical FCC cycle with the 5 core personas. This is the minimum viable workflow.

File: data/workflows/base_sequence.json

graph LR
    RC["RC: Research Crafter<br/>(Find)"]
    BC["BC: Blueprint Crafter<br/>(Create)"]
    DE["DE: Documentation Evangelist<br/>(Critique)"]
    RB["RB: Runbook Crafter<br/>(Create)"]
    UG["UG: User Guide Crafter<br/>(Create)"]

    RC -->|research_inventory| BC
    BC -->|blueprints_specs| DE
    DE -->|publish_handoff| RB
    DE -->|publish_handoff| UG
    BC -->|updated_specs| RB
    BC -->|updated_specs| UG

    DE -.->|standards_edits| BC
    RB -.->|operational_feedback| BC
    RB -.->|operational_findings| RC
    UG -.->|usability_feedback| BC
    UG -.->|user_feedback| RC

Nodes: 5 | Edges: 11 (6 handoff, 5 feedback)

The base graph encodes the core Find-Create-Critique cycle:

  1. RC gathers research and delivers the inventory to BC.
  2. BC creates blueprints and submits them to DE for review.
  3. DE critiques, then publishes to RB and UG.
  4. RB and UG provide feedback back to BC and RC, closing the loop.

Extended Graph (20 Nodes)

Adds all integration, governance, and stakeholder personas to the base graph.

File: data/workflows/extended_sequence.json

graph TB
    subgraph Find
        RC["RC"]
        CIA["CIA"]
        STE["STE"]
        RIC["RIC"]
        RS["RS"]
    end

    subgraph Create
        BC["BC"]
        UMC["UMC"]
        RB["RB"]
        UG["UG"]
        PTE["PTE"]
        EC["EC"]
        SCP["SCP"]
    end

    subgraph Critique
        DE["DE"]
        BV["BV"]
        GCA["GCA"]
        AMS["AMS"]
        SMC["SMC"]
    end

    subgraph All_Phases ["All Phases"]
        TS["TS"]
        DGS["DGS"]
        CO["CO"]
    end

    RC -->|research_inventory| BC
    CIA -->|indexed_assets| RC
    CIA -->|catalog_data| BC
    STE -->|terminology_standards| RC
    STE -->|classification_schemas| DGS
    RIC -->|structured_data| BC
    RIC -->|capability_data| CIA
    RC -->|requirements| TS

    BC -->|blueprints_specs| DE
    BC -->|blueprints_validation| BV
    BC -->|specs_for_mockup| UMC
    BC -->|updated_specs| RB
    BC -->|updated_specs| UG
    UMC -->|mockup_review| BV
    UMC -->|visual_assets| UG
    DGS -->|governance_context| BC
    DGS -->|integration_data| PTE
    PTE -->|privacy_compliance| GCA
    PTE -->|classification_context| AMS

    DE -->|publish_handoff| RB
    DE -->|publish_handoff| UG
    DE -->|approved_docs| SCP
    BV -->|quality_issues| DE
    BV -->|compliance_results| GCA
    AMS -->|validation_results| GCA
    GCA -->|governance_status| CO
    TS -->|compliance_gaps| GCA

    CO -->|status_updates| EC
    SMC -->|metrics| EC
    SMC -->|trends| RS
    EC -->|executive_packages| SCP
    RS -->|roadmap_data| EC
    UG -->|user_guides| SCP

Nodes: 20 | Edges: 40 (34 handoff, 6 feedback)

The extended graph introduces specialized workflows:

  • Indexing pipeline: CIA and STE feed enriched data into the core cycle.
  • Validation pipeline: BC sends blueprints to BV for quality validation, and UMC submits mockups for review.
  • Governance pipeline: DGS feeds PTE feeds AMS feeds GCA, ensuring progressive compliance validation.
  • Stakeholder pipeline: CO, SMC, EC, RS, and SCP form a reporting and publishing chain.

Complete Graph (24 Nodes)

Adds the 4 Champion personas with orchestration edges.

File: data/workflows/complete_24.json

graph TB
    subgraph Champions
        RCHM["RCHM: Research Champion"]
        BCHM["BCHM: Blueprint Champion"]
        UGCH["UGCH: User Guide Champion"]
        RBCH["RBCH: Runbook Champion"]
    end

    subgraph Find
        RC["RC"]
        CIA["CIA"]
        STE["STE"]
        RIC["RIC"]
    end

    subgraph Create
        BC["BC"]
        UMC["UMC"]
        BV["BV"]
    end

    subgraph Critique
        DE["DE"]
        GCA["GCA"]
        TS["TS"]
    end

    subgraph Delivery
        UG["UG"]
        RB["RB"]
        SCP["SCP"]
        EC["EC"]
    end

    %% Champion orchestration
    RCHM -.->|orchestrate| RC
    RCHM -.->|orchestrate| CIA
    RCHM -.->|orchestrate| STE
    RCHM -.->|orchestrate| RIC
    RCHM -->|research_package| BCHM

    BCHM -.->|orchestrate| BC
    BCHM -.->|orchestrate| BV
    BCHM -.->|orchestrate| UMC
    BCHM -.->|orchestrate| RIC
    BCHM -->|blueprint_package| DE
    BCHM -->|blueprint_for_ops| RBCH

    UGCH -.->|orchestrate| UG
    UGCH -.->|orchestrate| SCP
    UGCH -.->|orchestrate| EC
    DE -->|approved_for_publishing| UGCH

    RBCH -.->|orchestrate| RB
    RBCH -.->|orchestrate| GCA
    RBCH -.->|orchestrate| TS

Nodes: 24 | Edges: 52 (all extended edges + 18 champion edges)

The complete graph adds a coordination layer on top of the extended graph:

  • RCHM orchestrates all Find-phase personas (RC, CIA, STE, RIC) and delivers a unified research package to BCHM.
  • BCHM orchestrates blueprint creation (BC, BV, UMC, RIC) and delivers to both DE and RBCH.
  • RBCH orchestrates operational readiness (RB, GCA, TS) and validates compliance before deployment.
  • UGCH orchestrates user-facing delivery (UG, SCP, EC) after receiving approved content from DE.

Traversal

The WorkflowGraph.bfs_from(start_id) method performs a breadth-first traversal from any starting node, following all edge types (handoff, feedback, and orchestration). This is the primary traversal used by the simulation engine.

graph = WorkflowGraph.from_json("data/workflows/base_sequence.json")
order = graph.bfs_from("RC")
# Returns: ['RC', 'BC', 'DE', 'RB', 'UG']

BFS guarantees that every reachable node is visited exactly once, even in graphs with feedback cycles.

Topological Sort

The WorkflowGraph.topological_order() method uses Kahn's algorithm to produce a deterministic ordering. Only handoff edges are considered -- feedback edges are excluded to break cycles.

order = graph.topological_order()
# Returns a valid topological ordering of nodes

Topological ordering is useful for determining the natural execution order of the workflow without feedback-driven revisitation.

Query Methods

The WorkflowGraph class provides rich query capabilities:

  • successors(node_id) -- Nodes reachable via outgoing edges
  • predecessors(node_id) -- Nodes with incoming edges to the target
  • outgoing_edges(node_id) -- All outgoing edges from a node
  • incoming_edges(node_id) -- All incoming edges to a node
  • edges_by_type(edge_type) -- All edges of a given type
  • handoffs() -- All handoff edges
  • feedbacks() -- All feedback edges