Skip to content

Contributing

Contributions to the FCC Agent Team Framework are welcome. This guide covers the development setup, code style conventions, testing requirements, and pull request process.

Development Setup

Prerequisites

  • Python 3.11 or later
  • Make (for build automation)
  • Git

Setup

# Clone the repository
git clone https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext.git
cd l2_fcc_agent_team_ext

# Create virtual environment and install dependencies
make venv
source .venv/bin/activate
make install-dev

The make install-dev command installs the package in editable mode (pip install -e .) with all development dependencies (pytest, pytest-cov, ruff).

Verify Setup

make test    # Should run 1060 tests with 100% coverage
make lint    # Should report no issues

Code Style

The project uses Ruff for linting and formatting.

Key Conventions

  • Line length: 120 characters maximum
  • Import sorting: Ruff's isort-compatible sorting
  • Type hints: Use from __future__ import annotations in all modules for PEP 604 union syntax (X | Y)
  • Docstrings: Required for all public classes and functions. Use imperative mood for the first line.
  • Dataclasses: Use @dataclass(frozen=True) for all model classes. Do not use Pydantic.
  • CLI: Use click for all command-line interfaces. Do not use argparse.
  • No enterprise-specific content: This is a reusable framework. Keep organization-specific details out of the codebase.

Running the Linter

make lint           # Check for issues
ruff check --fix    # Auto-fix where possible
ruff format         # Format code

Testing Requirements

Coverage Policy

  • Minimum coverage: 99%
  • Target coverage: 100% (currently achieved)
  • Current test count: 1060 tests

Every pull request must maintain or improve coverage. A PR that drops coverage below 99% will not be merged.

Test Organization

Tests mirror the source structure:

tests/
├── test_personas/
│   ├── test_models.py
│   ├── test_registry.py
│   ├── test_dimensions.py
│   └── test_cross_reference.py
├── test_workflow/
│   ├── test_models.py
│   └── test_graph.py
├── test_simulation/
│   ├── test_engine.py
│   ├── test_ai_engine.py
│   ├── test_ai_client.py
│   ├── test_prompts.py
│   ├── test_messages.py
│   └── test_traces.py
├── test_scenarios/
│   ├── test_models.py
│   ├── test_loader.py
│   └── test_validators.py
├── test_scaffold/
│   ├── test_cli.py
│   ├── test_doc_generator.py
│   ├── test_engine.py
│   └── test_project.py
└── test_governance/
    ├── test_quality_gates.py
    ├── test_tags.py
    └── test_compliance.py

Running Tests

make test                        # Full test suite with coverage
pytest tests/ -v                 # Verbose output
pytest tests/test_personas/ -v   # Run a specific module
pytest -k "test_bfs"             # Run tests matching a pattern

See the Testing Guide for detailed patterns and conventions.

Pull Request Process

For the complete end-to-end workflow including branch protection setup, CI verification, review and merge process, and AI-assisted development with Claude Code, see the PR Workflow Guide.

Before Submitting

  1. Branch from main: Create a feature branch from the latest main.
  2. Write tests first: Add tests for new functionality before implementing it.
  3. Run the full suite: make test && make lint must both pass.
  4. Check coverage: Coverage must remain at 99% or above.
  5. Update documentation: If your change affects the public API, update relevant docs.

PR Description

Include in your PR description:

  • Summary: What the change does and why it is needed.
  • Test plan: How the change was tested.
  • Coverage impact: Whether coverage changed and why.

Review Process

  • All PRs require at least one review before merging.
  • CI must pass (tests, lint, coverage check).
  • Merge commits are preferred over squash for traceability.

What Makes a Good Contribution

  • New personas -- Follow the Extension Guide and include full R.I.S.C.E.A.R. specifications, quality gates, capability tags, and tests.
  • New simulation modes -- Add to the engine layer with both mock and AI-powered implementations.
  • Bug fixes -- Include a test that reproduces the bug before the fix.
  • Documentation improvements -- Fix inaccuracies, add examples, improve clarity.
  • Performance improvements -- Include benchmarks showing the improvement.

License

This project is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same terms.