Skip to content

Quickstart: Your First Simulation

Run your first FCC simulation from scratch. No API keys, no external services, no prior experience required.

You will need approximately 10 minutes.

Prerequisites

  • Python 3.10 or later (check with python --version)
  • pip (included with standard Python installations)
  • A terminal (macOS Terminal, Windows PowerShell, or Linux shell)

Note: FCC runs entirely offline in mock mode. You do not need an Anthropic or OpenAI API key for this guide.

Step 1: Install FCC

Install from PyPI:

pip install fcc-agent-team-ext

Or, if you prefer an editable install from source:

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
python -m venv .venv
source .venv/bin/activate    # On Windows: .venv\Scripts\activate
pip install -e .

Verify the installation:

fcc --help

You should see output listing the available commands:

Usage: fcc [OPTIONS] COMMAND [ARGS]...

  FCC (Find -> Create -> Critique) Agent Team Framework.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  action          Manage and run persona workflow actions.
  benchmark       Run benchmark assessments.
  collab          Manage human-agent collaboration sessions.
  compliance-audit Run EU AI Act / NIST AI RMF compliance audit.
  dashboard       Display terminal dashboards for FCC data.
  demo            Demo commands.
  generate-docs   Generate docs-as-code documentation from persona specs.
  init            Initialize a new FCC project.
  model-card      Generate model cards and datasheets.
  plugins         Manage FCC plugins.
  protocol        Protocol integration commands (A2A, MCP).
  simulate        Run an FCC workflow simulation.
  validate        Validate FCC project structure.
  ...

Tip: If you see command not found: fcc, make sure your virtual environment is activated: source .venv/bin/activate

Step 2: Run a Mock Simulation

FCC ships with 33 built-in scenarios. The default scenario, GEN-001, runs a 5-persona FCC cycle through the base workflow graph. Execute it in mock mode (no API keys needed):

fcc simulate --scenario GEN-001

You should see:

Simulation complete: 5 steps, 5 AI calls
Traces written to: traces_ai.json

The simulation traversed a 5-node workflow graph -- Research Crafter, Blueprint Crafter, Documentation Evangelist, Runbook Crafter, and User Guide Crafter -- and produced a trace at each step.

Tip: Mock mode generates deterministic output. Run the same command again and you will get identical results -- useful for testing and reproducibility.

Step 3: Inspect the Trace Output

Open traces_ai.json in any text editor or JSON viewer. Each trace event records:

  • step: The step number in the workflow traversal
  • persona_id: Which persona acted (e.g., RC for Research Crafter)
  • payload: The input given to the persona
  • edge_label: The workflow edge that led to this step
  • ai_response: The (mock) output produced by the persona
# Pretty-print the first few lines
python -c "import json; data=json.load(open('traces_ai.json')); print(json.dumps(data[:2], indent=2))"

Example trace entry:

{
  "step": 1,
  "persona_id": "RC",
  "edge_label": "start",
  "payload": "GEN-001",
  "ai_response": {
    "content": "Research Crafter analysis for scenario GEN-001...",
    "provider": "MOCK",
    "model": "mock-model"
  }
}

Step 4: Explore Personas from Python

Open a Python interpreter or script and explore the 102 built-in personas:

from fcc.personas.registry import PersonaRegistry

# Load all built-in personas
registry = PersonaRegistry.from_package_data()

print(f"Total personas: {len(registry.all())}")
print(f"Categories: {len(registry.categories())}\n")

# Look at one persona
persona = registry.get("research_catalyst")
print(f"Name: {persona.name}")
print(f"Category: {persona.category}")
print(f"Role: {persona.riscear.role}")
print(f"Archetype: {persona.riscear.archetype}")

Expected output:

Total personas: 102
Categories: 20

Name: Research Catalyst
Category: core
Role: Discover and synthesize knowledge from diverse sources...
Archetype: The Explorer

Step 5: Run a Simulation from Python

You can also run simulations programmatically for more control:

from fcc.simulation.engine import SimulationEngine
from fcc.scenarios.loader import ScenarioLoader

# Load built-in scenarios
scenarios = ScenarioLoader.from_package_data()
scenario = scenarios.get("basic_fcc_cycle")
print(f"Scenario: {scenario.title}")

# Load personas
from fcc.personas.registry import PersonaRegistry
registry = PersonaRegistry.from_package_data()

# Run in mock mode (deterministic, no API key)
engine = SimulationEngine(registry=registry, mode="mock")
trace = engine.run(scenario)

print(f"\nCompleted in {trace.duration_ms}ms")
print(f"Steps: {len(trace.steps)}\n")

for step in trace.steps:
    print(f"  [{step.phase}] {step.persona_id}: {step.summary[:60]}...")

Expected output:

Scenario: Basic FCC Cycle

Completed in 12ms
Steps: 5

  [FIND] research_catalyst: Research Catalyst discovers relevant inform...
  [CREATE] build_champion: Build Champion synthesizes findings into a ...
  [CREATE] documentation_evangelist: Documentation Evangelist structures...
  [CRITIQUE] domain_expert: Domain Expert reviews the deliverable for ...
  [CRITIQUE] governance_compliance_auditor: Governance Auditor verifies...

Step 6: Understand What Happened

Here is what happened in your simulation:

  1. Personas loaded: The PersonaRegistry loaded 102 persona definitions from YAML files bundled with the FCC package. Each persona has a full R.I.S.C.E.A.R. specification (Role, Input, Style, Constraints, Expected Output, Archetype, Responsibilities, Skills, Collaborators, Adoption Checklist).

  2. Scenario selected: The scenario defines which personas participate and the workflow structure.

  3. FCC cycle executed: The simulation engine drove the Find-Create-Critique cycle:

  4. Find: Research Catalyst gathered and synthesized information.
  5. Create: Build Champion and Documentation Evangelist produced the deliverable.

  6. Critique: Domain Expert and Governance Auditor reviewed the output.

  7. Trace captured: Every step was recorded in a structured trace, enabling replay, analysis, and reproducibility.

Note: In mock mode, all responses are deterministic and pre-generated. To use real AI providers (Anthropic or OpenAI), set the ANTHROPIC_API_KEY or OPENAI_API_KEY environment variable and run with --no-mock.

Step 7: Try the Terminal Dashboards

FCC includes ASCII dashboards for exploring the ecosystem from your terminal:

# Browse all 102 personas by category
fcc dashboard personas

# View quality gate status
fcc dashboard quality

# See the ecosystem overview
fcc dashboard ecosystem

These dashboards render directly in your terminal -- no browser needed.

What's Next

You have installed FCC, run your first simulation, and inspected the output. Here are the recommended next steps:

  • Learn the vocabulary: Read the Glossary for definitions of key FCC terms (persona, R.I.S.C.E.A.R., workflow, trace, quality gate).
  • Take a visual tour: See the Visual Tour to explore the web frontend with D3.js visualizations.
  • Interactive notebook: Open notebooks/01_fcc_fundamentals.ipynb in Jupyter for a hands-on walkthrough of personas, workflows, and simulations.
  • Try more scenarios: List all 33 scenarios with fcc demo list and run guided demos with fcc demo run <demo_id>.
  • Run workflow actions: List available actions with fcc action list and run one with fcc action run scaffold --persona RC.
  • Follow a learning path: See the Learning Paths guide to find the right track for your goals.
  • Full reference: Read the FAQ for answers to common questions.

Troubleshooting

"ModuleNotFoundError: No module named 'fcc'"

Make sure you activated your virtual environment:

source .venv/bin/activate    # Linux/macOS
.venv\Scripts\activate       # Windows

"command not found: fcc"

The CLI entry point is installed with the package. Verify:

pip show fcc-agent-team-ext

If installed, try python -m fcc as an alternative.

"No workflow found" when running fcc simulate

The simulate command looks for workflow files relative to the current directory. Make sure you are in the project root, or use the --dir flag:

fcc simulate --scenario GEN-001 --dir /path/to/l2_fcc_agent_team_ext