Skip to content

Your First 30 Minutes with FCC

A timed, minute-by-minute walkthrough for brand-new users. By the end you will have installed FCC, run a simulation, read a trace, inspected a persona, and edited a YAML file.

No AI API keys required -- everything here runs in mock mode.

The 30-Minute Arc

flowchart LR
    A["0–5 min<br/>Install"] --> B["5–10 min<br/>First simulation"]
    B --> C["10–15 min<br/>Read the trace"]
    C --> D["15–20 min<br/>Explore a persona"]
    D --> E["20–30 min<br/>Edit a YAML"]
    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
    style D fill:#f3e5f5
    style E fill:#fce4ec

Before You Start

  • Python 3.10+
  • Git
  • A terminal (macOS/Linux shell, WSL, or PowerShell)
  • About 30 minutes
  • No API keys needed

0-5 min: Install (budget 5 minutes)

Clone, create a virtual environment, install:

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      # Windows: .venv\Scripts\activate
pip install -e .

Verify:

fcc --version

Expected output:

fcc, version 1.3.3

Troubleshooting - What if pip install fails? The two most common causes are (a) Python older than 3.10 and (b) a missing C compiler on Linux. Run python --version to check version. On Debian/Ubuntu try sudo apt install build-essential python3-dev. Windows users should install the Microsoft C++ Build Tools.

5-10 min: Run your first simulation (budget 5 minutes)

Open a Python REPL:

python

Now run:

from fcc.personas.registry import PersonaRegistry
from fcc.scenarios.loader import ScenarioLoader
from fcc.simulation.engine import SimulationEngine

registry = PersonaRegistry.from_package_data()
scenarios = ScenarioLoader.from_package_data()
scenario = scenarios.get("basic_fcc_cycle")

engine = SimulationEngine(registry=registry, mode="mock")
trace = engine.run(scenario)

print(f"Duration: {trace.duration_ms} ms")
print(f"Steps:    {len(trace.steps)}")

Expected output (values will vary):

Duration: 37 ms
Steps:    6

That's it -- you ran an end-to-end FCC cycle in mock mode.

Troubleshooting - What if no AI provider is configured? Nothing breaks. Mock mode is always available and deterministic. AI providers (anthropic, openai, ollama, litellm) are only engaged when you set mode="ai" and the relevant env var is set. See the AI provider matrix for details.

10-15 min: Read the trace (budget 5 minutes)

A trace records every step: which persona acted, which phase (FIND / CREATE / CRITIQUE), and a summary.

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

Expected output excerpt:

[FIND    ] research_catalyst         Surveyed the problem space and identified ...
[FIND    ] evidence_gatherer         Collected supporting data points ...
[CREATE  ] solution_architect        Drafted an initial solution outline ...
[CRITIQUE] critique_lead             Reviewed draft against quality gates ...

Three things to notice:

  1. Each step is attributed to a persona -- you can always audit "who did what".
  2. The phase tells you where in the Find-Create-Critique cycle the step sits.
  3. The summary is short on purpose. Full content is available on each step via step.output.

15-20 min: Explore a persona (budget 5 minutes)

Each persona follows the 10-component R.I.S.C.E.A.R. specification.

persona = registry.get("research_catalyst")

print(f"Name:     {persona.name}")
print(f"Category: {persona.category}")
print(f"Role:     {persona.riscear.role}")
print(f"Style:    {persona.riscear.style}")
print(f"Archetype:{persona.riscear.archetype}")
print()
print("Responsibilities:")
for r in persona.riscear.responsibilities:
    print(f"  - {r}")

Expected output excerpt:

Name:     Research Catalyst
Category: open_science
Role:     Surface high-leverage research questions ...
Style:    Probing, generative, hypothesis-rich
Archetype: The Navigator

Try a different persona to compare:

print(registry.get("compliance_guardian").riscear.role)

20-30 min: Edit a YAML (budget 10 minutes)

FCC personas are plain YAML under src/fcc/data/personas/. You can author your own in a separate directory and layer them on top.

Create my_personas/friendly_explainer.yaml:

id: friendly_explainer
name: Friendly Explainer
category: docs_as_code
riscear:
  role: "Explain technical concepts in plain language"
  input: "Any technical topic"
  style: "Warm, patient, example-heavy"
  constraints: "Avoid jargon; always include at least one analogy"
  expected_output: "Plain-English explanation plus 1 analogy"
  archetype: "The Teacher"
  responsibilities:
    - "Translate technical concepts for non-specialists"
    - "Produce analogies and worked examples"
  role_skills:
    - "Technical writing"
    - "Analogy generation"
  role_collaborators: []
  role_adoption_checklist:
    - "Identify target audience reading level"
    - "Gather source material"

Load it alongside the built-ins:

registry = PersonaRegistry.from_package_data()
registry.load_directory("my_personas/")

print(registry.get("friendly_explainer").name)

Expected output:

Friendly Explainer

You can now reference this persona in custom scenarios, plug it into a workflow, or generate docs-as-code for it.

Troubleshooting - Validation errors when loading YAML? FCC validates every persona against the R.I.S.C.E.A.R. JSON schema. A missing required field (like archetype) raises a ValidationError with the offending path. See common mistakes for the 15 most frequent errors.

What next?

You have just done the complete beginner loop. Recommended follow-ups:

Cheat sheet

Goal One-liner
Check version fcc --version
Load all personas PersonaRegistry.from_package_data()
Run mock simulation SimulationEngine(registry, mode="mock").run(scenario)
List categories registry.categories()
Validate docs fcc validate-docs --input-dir ./generated-docs

Welcome to FCC. The rest of the framework builds on exactly these primitives.