Skip to content

Getting Started (Students)

This page gets you from a fresh laptop to a running FCC scenario in about 45 minutes, including time to understand what you just ran.

Before you start

You need:

  • Python 3.11 or newer. Check with python --version.
  • Git.
  • A text editor with YAML syntax highlighting (VS Code, Neovim, Sublime).
  • About 500 MB of disk space.
  • An internet connection for the initial install (the runtime works offline).

You do not need:

  • Any AI-provider account or API key.
  • Docker or Kubernetes.
  • Admin privileges on your machine.

Step 1: Clone and 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      # on Windows: .venv\Scripts\activate
pip install -e .[dev]

The -e flag makes it an editable install, so you can hack on the code and see changes immediately. The [dev] extra installs pytest and ruff so you can run the test suite and linter.

Step 2: Verify

fcc --version
fcc personas list --limit 10

You should see 1.7.0 (or higher) and a short list of personas. If fcc is not on your PATH, check that the virtualenv is activated.

Step 3: Run your first scenario

Pick a small scenario:

fcc scenarios list | head
fcc run scenarios/hello-fcc.json --provider mock

The --provider mock flag forces deterministic output — no LLM is called. You will see a structured trace printed to the terminal, ending with a summary of how many personas participated and which action types were executed.

Step 4: Inspect the trace

fcc run scenarios/hello-fcc.json --provider mock --trace out/trace.json
cat out/trace.json | python -m json.tool | less

The trace is a tree of events: persona activations, action calls, messages between personas, and final outputs. This is the artifact you will analyze for almost any student project.

Step 5: Read a persona

fcc personas show knowledge-finder

(You can substitute any persona ID from fcc personas list.) The output shows the full R.I.S.C.E.A.R. spec, category, risk category, and collaborator list. Notice the responsibilities and constraints lists — these are the most instructive fields for first-time readers.

Step 6: Author your first persona

Create a file my_persona.yaml in your home directory:

id: study-buddy
category: core
risk_category: minimal
riscear:
  role: "Summarizes course readings into 5-bullet outlines."
  input: "A PDF or Markdown course reading."
  style: "Bullet-first. Each bullet <=20 words."
  constraints:
    - "Must preserve author attributions."
    - "Never invent citations."
  expected_output: "Markdown with 5 bullets plus a 1-sentence summary."
  archetype: "Summarizer"
  responsibilities:
    - "Flag claims that lack supporting citation."
  role_skills:
    - "Academic summarization"
  role_collaborators: []
  role_adoption_checklist:
    - "Verify summary against source before using in papers."

Validate it:

fcc personas validate my_persona.yaml

If the validator objects, it will tell you which field is missing or malformed. Fix and re-run until it passes.

Step 7: Use your persona in a scenario

Create my_scenario.json:

{
  "name": "my-first-scenario",
  "personas": ["study-buddy"],
  "workflow": "base-5",
  "inputs": {
    "reading": "Paste your reading text here or reference a local file."
  },
  "setup": { "ai_config": { "provider": "mock" } }
}

Run it:

fcc run my_scenario.json --persona-dir ~ --trace out/my_trace.json

You just authored a persona, wired it into a scenario, and produced a structured trace. This is the minimum viable loop for almost every assignment.

Step 8: Run the tests

make test

For many software-engineering assignments, you will be asked to add a test. The test tree mirrors the source tree under tests/. Open tests/personas/test_registry.py and read a couple of tests to see the patterns.

Common first-time mistakes

  • YAML indent errors. FCC uses standard YAML; two-space indent, no tabs.
  • Forgetting --provider mock. Without it, FCC will try to auto-detect a provider and may emit a warning if none is configured. This is harmless but noisy.
  • Running from the wrong directory. CLI paths are relative to your current working directory. Use absolute paths when in doubt.

Troubleshooting

  • ModuleNotFoundError: No module named 'fcc' — your virtualenv is not activated, or you skipped pip install -e ..
  • JSONSchema ValidationError — your scenario or persona file does not conform. The error message names the offending field.
  • No personas found — you forgot --persona-dir when loading a persona outside the package.

Where next

You have a working install and a custom persona. Go to Assignment Patterns to find a project shape, or R.I.S.C.E.A.R. Exercise for deliberate practice on persona authoring.