Skip to content

Getting Started (Open-Source Maintainers)

A brisk orientation. By the end of this page you will know whether it is worth your time to continue with this track.

Clone and poke around (10 minutes)

git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext
ls -la

The repo is a standard Python project with src/fcc/ layout. A few things worth spotting:

  • CLAUDE.md — project overview, maintained as a living document.
  • Makefile — make test, make lint, make install-dev, make docker-up. Note the convention: every common action has a make target.
  • docs/ — extensive; lives alongside code; driven by Jinja templates.
  • src/fcc/data/ — YAML and JSON are packaged with the wheel via importlib.resources. No Path(__file__) tricks.
  • docs/decisions/ — 5 ADRs. Short, dated, numbered.
  • RELEASE_NOTES.md — a single file with the full release history.

If these patterns already feel familiar, you know the playbook; this track will mostly sharpen the edges. If they are new, there is real value in reading further.

Read the release history (10 minutes)

Skim RELEASE_NOTES.md. Look for:

  • Frequency of releases (roughly monthly; short periods of more frequent patches).
  • Shape of version numbers (semantic versioning, with occasional four-part during patch clusters such as v1.3.5.1 → v1.3.5.4).
  • Pattern of "planned vs. shipped" (nearly all releases match the plan; that is itself a discipline).

Read one ADR (15 minutes)

Open docs/decisions/0001-plugin-system.md or whichever title catches your eye. Notice:

  • The structure: Context, Decision, Consequences, Alternatives.
  • The length: 2-4 pages each.
  • The tone: narrative, not bullet-soup.
  • The cross-references to other ADRs.

This is a pattern you can adopt in an afternoon.

Read one persona YAML (5 minutes)

ls src/fcc/data/personas/core/

Pick any file and read it. You are reading the R.I.S.C.E.A.R. specification in the wild. Notice how the ten fields combine to produce a role definition that is self-describing enough to be useful without separate documentation.

Read the Makefile (5 minutes)

Targets to look at:

  • install-dev — standard editable install.
  • test — runs pytest with coverage.
  • lint — ruff.
  • docker-{build,up,down,logs,test} — one-command stack management.
  • pub-all — builds the full publications pipeline.

Every common maintainer task has a target. When a new contributor joins, "make test" is the whole onboarding story.

Is this track worth your time?

Answer yes to at least three of these and continue:

  • My project has contributors who onboard slowly.
  • I have felt "docs drift" in the last six months.
  • I want a more systematic role-definition pattern.
  • I like having ADRs for architectural decisions.
  • I am considering a plugin system or extension surface.
  • My release cadence is ad-hoc and I want to improve it.

If you answered yes three or more times, keep reading.

What to ignore in this repo

FCC has many pieces that are unique to it. On a first pass you can skip:

  • src/fcc/compliance/ — AI-regulation-specific.
  • src/fcc/evaluation/ — benchmark framework.
  • src/fcc/simulation/ — the AI runtime.
  • All vertical packs under src/fcc/data/personas/.
  • publications/ — specialized multi-format publishing.
  • notebooks/ — demos.

What to focus on for pattern-extraction:

  • docs/ (overall organization)
  • docs/decisions/ (ADR shape)
  • docs/model-cards/ (auto-generated docs)
  • src/fcc/scaffold/ (the generator that builds those docs)
  • Makefile (developer ergonomics)
  • RELEASE_NOTES.md (cadence discipline)

Minimal first experiment

If you want to try something small:

  1. Pick one module in your project.
  2. Write a R.I.S.C.E.A.R.-inspired role definition for that module. (See Adopting R.I.S.C.E.A.R..)
  3. Commit it as src/<your-module>/ROLE.yaml.
  4. Open a PR; ask contributors whether it helps them understand the module.

A single module experiment takes about 90 minutes and produces evidence. If the evidence is negative, nothing is lost.

Relationship to the FCC Python package

You do not need to import or install the FCC Python package to adopt any of these patterns. The repository is a pattern museum as much as a software artifact. Grep it. Read it. Borrow what works.

Where next

Go to Adopting R.I.S.C.E.A.R. for the core-pattern exercise, or to Docs-as-Code Patterns if your main pain is documentation drift.