Skip to content

Extension Guide

The FCC framework is designed to be extended without modifying the core package. This guide covers the five primary extension points: custom personas, templates, quality gates, scenarios, and capability tags.

Adding Custom Personas

Step 1: Define the Persona YAML

Create a new YAML file under data/personas/ or add entries to an existing file. Each persona requires a full R.I.S.C.E.A.R. specification:

personas:
  - id: SR
    name: Security Reviewer
    fcc_phase: Critique
    role_title: Security Audit Specialist
    color: "#D32F2F"
    category: governance
    riscear:
      role: >-
        Reviews documentation and blueprints for security vulnerabilities
        and compliance with security standards.
      inputs:
        - Blueprint artifacts from Blueprint Crafter
        - Security policies and standards
        - Threat models and risk assessments
      style: >-
        Security-focused, evidence-based, risk-prioritized analysis.
      constraints:
        - All findings must reference specific security standards
        - Critical vulnerabilities must be flagged immediately
        - Remediation guidance must be actionable
      expected_output:
        - Security review reports with severity ratings
        - Remediation recommendations
        - Compliance verification results
      archetype: The Sentinel
      responsibilities:
        - Review all artifacts for security vulnerabilities
        - Maintain security standards documentation
        - Provide actionable remediation guidance
      role_skills:
        - Security audit methodology
        - Threat modeling and risk assessment
        - Compliance framework application
      role_collaborators:
        - Reviews blueprints from Blueprint Crafter (BC)
        - Reports findings to Governance Compliance Auditor (GCA)
      role_adoption_checklist:
        - Security review checklist covers all artifact types
        - Severity rating criteria documented
        - Remediation guidance is actionable with clear steps
    doc_context:
      primary_action: "security review"
      primary_output: "security review reports"
      cli_command: "scaffold-sr"
      example_scenario: "Review an API blueprint for authentication and authorization vulnerabilities"

Step 2: Register in the Registry

The PersonaRegistry.from_yaml_directory() method automatically discovers all YAML files in the personas directory. No explicit registration is needed -- just place the file in data/personas/.

Step 3: Add to Workflow Graph

Add the persona as a node and define its edges in the appropriate workflow JSON file:

{
  "id": "SR",
  "name": "Security Reviewer",
  "type": "persona"
}

Add edges connecting the persona to existing nodes:

{"from": "BC", "to": "SR", "label": "blueprints_security_review", "type": "handoff"},
{"from": "SR", "to": "GCA", "label": "security_findings", "type": "handoff"}

Step 4: Add Dimension Profile (Optional)

Create data/personas/dimensions/sr_profile.yaml with dimension values for the new persona. Use existing profiles as templates.

Step 5: Validate

fcc validate
fcc generate-docs --personas SR

Adding Custom Templates

Templates live under src/fcc/templates/ in two categories:

Scaffold Templates (src/fcc/templates/scaffold/)

Used by fcc init to generate project structure. Create new Jinja2 templates (.j2) and register them in the TemplateEngine.

Documentation Templates (src/fcc/templates/docs/)

Used by fcc generate-docs to produce per-persona documentation. The 15 existing templates generate tutorials, prompts, and workflows. To add a new doc type:

  1. Create a Jinja2 template under src/fcc/templates/docs/.
  2. Use the persona context variables: {{ persona.id }}, {{ persona.name }}, {{ persona.riscear.role }}, etc.
  3. Register the template in DocGenerator._generate_persona_docs().

Template variables available in doc templates:

Variable Type Description
persona PersonaSpec The full persona specification
persona.riscear RISCEARSpec The 10-component R.I.S.C.E.A.R. spec
persona.deliverables list[Deliverable] Named deliverables
persona.collaboration list[Collaboration] Collaboration links
persona.doc_context dict Documentation metadata
tutorial_topics list Tutorial topic definitions
prompt_topics list Prompt topic definitions

Adding Custom Quality Gates

Quality gates are defined in data/governance/quality_gates.yaml. To add a new gate:

- id: QG-SR-001
  name: Security Review Completeness
  persona_id: SR
  threshold: 1.0
  checks:
    - security_review_report
    - severity_ratings_assigned
    - remediation_recommendations

The gate ID convention is QG-<PERSONA_ID>-<SEQUENCE>. Use threshold 1.0 for gates where all checks must pass, or a lower value (e.g., 0.75) for gates where partial completion is acceptable.

Gate evaluation logic in src/fcc/governance/quality_gates.py automatically picks up new gates from the YAML file.

Adding Custom Scenarios

Scenarios define simulation parameters and are stored in data/scenarios/. Two scenario files exist:

  • starter_scenarios.json -- Basic scenarios for initial testing
  • advanced_scenarios.json -- Complex multi-phase scenarios

To add a custom scenario:

{
  "id": "SEC-001",
  "title": "Security Audit Workflow",
  "description": "Simulate a security review cycle across all blueprints",
  "start_node": "BC",
  "steps": [
    {
      "persona_id": "BC",
      "action": "produce_blueprint",
      "expected_output": "architecture_blueprint"
    },
    {
      "persona_id": "SR",
      "action": "security_review",
      "expected_output": "security_report"
    }
  ]
}

The FCCValidator.from_registry() method enables registry-aware scenario validation, ensuring that all persona IDs referenced in scenarios exist in the registry.

Adding Custom Capability Tags

Tags are defined in data/governance/tag_registry.yaml. To add a new tag:

- capability: persona-security-reviewer
  category: governance-compliance
  supercategory: strategy-alignment

Follow the naming convention: persona-<kebab-case-name> for persona tags, workflow-<name> for workflow tags, and <domain>-<name> for other capabilities.

Use existing categories where possible:

  • knowledge-sharing -- Research, design, review
  • integration-automation -- Indexing, validation, taxonomy
  • governance-compliance -- Governance, privacy, safety
  • stakeholder-engagement -- Coordination, metrics, publishing
  • champion-orchestration -- Champion personas
  • workflow-automation -- Workflow definitions
  • testing-validation -- Simulation and testing

Validation Checklist

After any extension, verify:

  • make test passes with no failures
  • make lint reports no issues
  • fcc validate confirms project structure
  • fcc generate-docs succeeds for the new persona
  • fcc validate-docs finds no empty files