Skip to content

Developer Guide

This section covers the technical architecture, tooling, and contribution workflow for the FCC Agent Team Framework. Whether you are extending the framework with custom personas, integrating it into a downstream project, or contributing upstream, start here.

Quick Start

# Clone and set up the development environment
git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
make venv && source .venv/bin/activate
make install-dev
make test    # 1030+ tests, 100% coverage
make lint    # ruff check

Key Modules

Module Path Purpose
personas src/fcc/personas/ Models, registry, dimensions, cross-reference matrix
workflow src/fcc/workflow/ Graph models, BFS/topological traversal
simulation src/fcc/simulation/ Engine, AI client, persona-aware prompts, traces
scenarios src/fcc/scenarios/ Scenario models, loading, dynamic validation
scaffold src/fcc/scaffold/ CLI tool, template engine, doc generator
governance src/fcc/governance/ Tags, quality gates, compliance scoring

Section Contents

  • Architecture -- System architecture with data flow diagrams, module walkthrough, and design decisions.

  • CLI Reference -- Complete reference for the fcc command-line tool: init, add-persona, validate, simulate, generate-docs, validate-docs, and sitemap.

  • Extension Guide -- How to add custom personas, templates, quality gates, scenarios, and capability tags.

  • Contributing -- Development setup, code style conventions, testing requirements, and pull request process.

  • PR Workflow -- End-to-end pull request workflow: branch protection, CI checks, review and merge process, and AI-assisted development with Claude Code.

  • Testing Guide -- Testing patterns, coverage policy, fixture conventions, and parametrized testing strategies.

  • Cross-Reference API -- Full method reference for CrossReferenceEntry and CrossReferenceMatrix with code examples.

  • Contributing Cross-References -- Step-by-step guide for adding entries to the cross-reference matrix.