Skip to content

Chapter 1: Project Setup

Learning Objectives

By the end of this chapter you will be able to:

  1. Initialize a new FCC project using fcc init.
  2. Understand the generated directory layout and the purpose of each file.
  3. Configure project settings for personas, workflows, and simulation.
  4. Run the validation suite to confirm the project is correctly set up.
  5. Customize the project scaffold for your domain.

The flowchart below shows what fcc init produces and how the generated project loops through fcc validate until the configuration is clean.

flowchart TD
    INIT["fcc init my_project"] --> SCAFFOLD[Generate Directory Structure]
    SCAFFOLD --> CONFIG[fcc.yaml Configuration]
    SCAFFOLD --> PERS[personas/ Directory]
    SCAFFOLD --> WF[workflows/ Directory]
    SCAFFOLD --> SCEN[scenarios/ Directory]
    SCAFFOLD --> PLUG[plugins/ Directory]
    SCAFFOLD --> TMPL[templates/ Directory]
    CONFIG --> VAL["fcc validate"]
    VAL -->|Pass| RUN["fcc dashboard personas"]
    VAL -->|Fail| FIX[Fix Configuration]
    FIX --> VAL

    style INIT fill:#2196F3,color:#fff
    style RUN fill:#4CAF50,color:#fff

Running fcc validate repeatedly is cheap and non-destructive, so adopt the habit of running it after every change to fcc.yaml or the personas directory rather than deferring validation until commit time.

Initializing a Project

The FCC CLI provides a scaffolding command that generates a complete project structure:

fcc init my_project --template standard

This creates a directory called my_project/ with the following structure:

my_project/
├── fcc.yaml              # Project configuration
├── personas/             # Custom persona YAML files
│   └── .gitkeep
├── workflows/            # Custom workflow graph JSON files
│   └── .gitkeep
├── scenarios/            # Custom scenario files
│   └── .gitkeep
├── plugins/              # Custom plugin modules
│   └── __init__.py
├── templates/            # Custom Jinja2 templates
│   └── .gitkeep
├── output/               # Generated artifacts (gitignored)
│   └── .gitkeep
└── tests/                # Project-specific tests
    └── test_setup.py

The --template flag selects the project template. Three templates are available:

Template Description Personas Included
minimal Bare minimum for experimentation None (uses core catalog)
standard Full project with example personas 3 example personas
enterprise Governance-heavy with compliance personas 5 personas + governance config

The Configuration File

The fcc.yaml file is the central configuration for your project. Here is the default configuration for the standard template:

project:
  name: my_project
  version: "0.1.0"
  description: "An FCC-powered project"

personas:
  sources:
    - "personas/"           # Local persona YAML files
  include_core: true         # Also load the 102 core personas
  include_plugins: true      # Also load plugin-contributed personas

workflows:
  default: "base_sequence"   # Which graph to use by default
  sources:
    - "workflows/"           # Local workflow graph JSON files

simulation:
  mode: "mock"               # "mock" or "ai"
  provider: "anthropic"      # AI provider when mode is "ai"
  max_iterations: 3          # Maximum feedback loop iterations
  budget:
    max_tokens: 100000       # Token budget for AI simulations
    max_cost_usd: 5.00       # Cost cap for AI simulations

governance:
  constitutions: true        # Enable constitution checking
  quality_gates: true        # Enable quality gate evaluation
  tag_registry: true         # Enable tag-based classification

output:
  directory: "output/"
  format: "markdown"         # "markdown", "json", or "both"

Each section controls a different subsystem. Let us walk through the important settings.

Persona Sources

The personas.sources list tells the PersonaRegistry where to find persona YAML files. You can list multiple directories and the registry will merge them. Setting include_core: true means the 102 core personas are always available alongside your custom ones.

This design lets you override core personas by providing a custom YAML file with the same persona ID. Your local definition takes precedence over the core definition, allowing you to customize behavior without modifying the framework source.

Workflow Selection

The workflows.default setting selects which workflow graph is used when no graph is explicitly specified. You can reference any of the four built-in graphs (base_sequence, extended_sequence, complete_24, extended_84) or a custom graph in your workflows/ directory.

Simulation Budget

When using AI-powered simulation, the simulation.budget section prevents runaway costs. The engine tracks cumulative token usage and cost, halting the simulation if either limit is reached. This is critical in production environments where a feedback loop bug could otherwise consume your entire API budget.

Governance Toggles

Each governance feature can be individually enabled or disabled. For development, you might disable constitutions to reduce overhead. For production, all three should be enabled to ensure full governance coverage.

Validation

After initialization, validate your project:

cd my_project
fcc validate

The validator checks:

  1. Configuration syntax. Is fcc.yaml valid YAML with all required fields?
  2. Persona schemas. Do all persona YAML files in personas/ conform to the JSON schema?
  3. Workflow schemas. Do all workflow JSON files in workflows/ conform to the workflow schema?
  4. Scenario schemas. Do all scenario files in scenarios/ conform to the scenario schema?
  5. Plugin integrity. Can all referenced plugins be imported and do they implement their ABCs?
  6. Cross-references. Do persona collaborator references point to personas that actually exist?

Validation errors include the file path, line number, and a description of the problem. Fix all errors before proceeding.

Customizing the Scaffold

The scaffold is a starting point, not a straitjacket. Common customizations include:

Adding Domain-Specific Directories

If your project involves ML lifecycle management, you might add:

my_project/
├── data/                 # Training data and feature stores
├── models/               # Model artifacts
├── experiments/          # Experiment tracking

These directories are not managed by FCC directly, but your custom personas can reference them in their R.I.S.C.E.A.R. specifications.

Splitting Persona Files

The core framework stores multiple personas per YAML file (organized by category). For your project, you might prefer one file per persona for easier version control:

personas/
├── data_analyst.yaml
├── domain_expert.yaml
├── quality_reviewer.yaml

Both approaches work. The PersonaRegistry loads all YAML files in the configured directories, regardless of how many personas each file contains.

Environment-Specific Configuration

For multi-environment deployments (dev, staging, production), create environment-specific config overrides:

config/
├── fcc.yaml              # Base configuration
├── fcc.dev.yaml          # Development overrides
├── fcc.staging.yaml      # Staging overrides
├── fcc.prod.yaml         # Production overrides

Use the FCC_CONFIG environment variable or --config CLI flag to select the active configuration. Override files are merged with the base configuration, so you only need to specify the settings that differ.

Project-Level Tests

The scaffold includes a tests/test_setup.py file with basic smoke tests:

"""Smoke tests for project setup."""
from fcc.personas.registry import PersonaRegistry


def test_personas_load():
    """All configured personas load without error."""
    registry = PersonaRegistry()
    registry.load_all()
    assert len(list(registry.all())) > 0


def test_core_personas_available():
    """Core personas are available when include_core is true."""
    registry = PersonaRegistry()
    registry.load_all()
    analyst = registry.get("research_analyst")
    assert analyst is not None

Extend this file with tests specific to your custom personas and workflows as you build them. Run with:

pytest tests/ -v

Key Takeaways

  • fcc init generates a complete project scaffold with configuration, directories, and smoke tests.
  • Three templates (minimal, standard, enterprise) cover different project scales.
  • fcc.yaml configures personas, workflows, simulation, governance, and output.
  • The validator checks schema compliance, cross-references, and plugin integrity.
  • Customize the scaffold to fit your domain -- add directories, split files, create environment-specific overrides.
  • The PersonaRegistry merges core, plugin, and local personas, with local definitions taking precedence.

Cross-References

← Book 2 Index | Next: Chapter 2 -- Custom Personas →