fcc-agent-team-ext 0.2.0

FCC (Find → Create → Critique) Agent Team Framework

FCC Agent Team Extension

FCC (Find → Create → Critique) agent workflow framework — a clean, well-structured Python package for orchestrating documentation agent teams.

Quick Start

For Users

pip install fcc-agent-team-ext
fcc --version

For Contributors

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 && make lint

What is FCC?

FCC is a three-phase workflow for documentation creation:

1. Find — Research personas gather and synthesize information
2. Create — Design, operations, and user-facing personas produce artifacts
3. Critique — Review and governance personas ensure quality

24 personas across 5 categories collaborate through message-passing workflows with feedback loops:

Category	Count	Personas
Core	5	Research Crafter, Blueprint Crafter, Documentation Evangelist, Runbook Crafter, User Guide Crafter
Integration	7	Catalog Indexer Architect, UI Mockup Crafter, Semantic Taxonomy Engineer, Traceability Specialist, Blueprint Validator, Research Inventory Crafter, Governance Compliance Auditor
Governance	3	Data Governance Specialist, Privacy Taxonomy Engineer, Anti-fact Mitigation Specialist
Stakeholder	5	Collaboration Orchestrator, SAFe Metrics Crafter, Executive Communicator, Roadmap Synchronizer, Stakeholder Content Publisher
Champion	4	Research Crafter Champion, Blueprint Crafter Champion, User Guide Crafter Champion, Runbook Crafter Champion

Champions are elevated personas that orchestrate teams of base personas (e.g., Research Crafter Champion coordinates RC, CIA, STE, and RIC).

Who Is This For?

• Beginners / Students — Learn agent orchestration patterns, persona-based workflows, and documentation-as-code methodologies through a well-structured, tested codebase with comprehensive examples.
• Developers — Build agent-powered documentation pipelines using a modular Python framework with CLI tooling, simulation engines, and Jinja2 template generation.
• Researchers — Study the R.I.S.C.E.A.R. persona specification, 56-dimension persona profiling, Discernment Matrix, and Design Target Factors as formal models for human-AI collaboration.
• Practitioners — Deploy FCC workflows in enterprise settings with governance controls, quality gates, capability tagging, and Scaled Agile alignment.

R.I.S.C.E.A.R. Framework

The full R.I.S.C.E.A.R. specification defines personas with 10 core components:

Component	Purpose
Role	Identity and function
Input	Data and background information
Style	Tone, language, and format
Constraints	Limitations and requirements
Expected Output	Desired structure and detail
Archetype	Fundamental character/persona
Responsibilities	Duties and ethical obligations
Role Skills	Skills for job execution
Role Collaborators	Team collaboration patterns
Role Adoption Checklist	Integration validation

Plus: Discernment Matrix (6 traits), Design Target Factors (6 factors), and a 56-dimension Persona system across 9 categories — all 24 personas fully populated with dimension profiles, discernment matrices, and design target factors.

Key Concepts

• FCC Cycle — The three-phase workflow (Find → Create → Critique) that structures how documentation is researched, produced, and reviewed. Artifacts flow forward through phases, with feedback edges enabling iterative refinement.
• Personas — AI agent roles defined by the R.I.S.C.E.A.R. specification. Each persona has a specific function, communication style, constraints, and collaboration patterns. 24 personas span 5 categories.
• Champions — Elevated personas that orchestrate teams of base personas. Each champion coordinates 3-4 team members, enabling top-down coordination alongside bottom-up message passing.
• Cross-Reference Matrix — A queryable 100+ entry interaction map across 5 relationship types (handoff, feedback, coordination, governance, champion-of). Supports upstream, downstream, peer, and relationship-type queries to understand how all 24 personas collaborate.
• Workflow Graphs — Directed graphs where nodes are personas and edges are message-passing connections. Three predefined graphs (5-node, 20-node, 24-node) support different levels of complexity. Traversed via BFS for deterministic activation ordering.
• Scenarios — Predefined test cases that exercise specific FCC workflows. Each scenario specifies participating personas, the workflow graph, and validation rules. 17 scenarios cover basic through advanced orchestration patterns.
• Quality Gates — Automated validation checkpoints that enforce documentation standards. 28 gates with configurable severity (error, warning, info) ensure completeness, compliance, and structural integrity. Includes 3 cross-reference integrity gates.

Project Structure

src/fcc/
├── _resources.py    Centralized data/template path resolution (importlib.resources)
├── personas/        Persona models, R.I.S.C.E.A.R. specs, dimensions, registry, cross-reference matrix
├── workflow/        Workflow graph models, traversal, BFS
├── simulation/      Deterministic + AI-powered simulation engine
├── scenarios/       Scenario loading, dynamic validation framework
├── scaffold/        CLI tool (fcc init, add-persona, validate, generate-docs, sitemap)
├── governance/      Capability tags, quality gates, compliance
├── data/            Package data (included in wheel distribution)
│   ├── personas/    24 personas across 5 YAML files + cross-reference matrix + dimensions
│   ├── workflows/   3 workflow graphs (base 5-node, extended 20-node, complete 24-node)
│   ├── schemas/     JSON Schema for personas, workflows, traces, cross-references
│   ├── scenarios/   17 scenarios (6 starter + 11 advanced)
│   ├── governance/  Tag registry (30 tags) + quality gate definitions (28 gates)
│   └── docs/        Topic registries (21 tutorials, 24 prompts, constitution template)
└── templates/
    ├── project/     Jinja2 templates for project scaffolding
    └── docs/        15 Jinja2 templates for docs-as-code generation

tests/               1168 tests across 24 test files (100% coverage)

Architecture Overview

graph TB
    YAML[YAML Personas] --> REG[PersonaRegistry]
    REG --> SIM[Simulation Engine]
    REG --> DOC[Doc Generator]
    SIM --> TRACE[Traces]
    DOC --> DOCS[1,348 Doc Files]
    GOV[Governance] --> SIM
    CLI[fcc CLI] --> SIM
    CLI --> DOC

CLI

fcc init --name "my-project" --dir ./my-project          # Bootstrap FCC project
fcc add-persona "Custom Analyst" --phase Find --id CA    # Add persona
fcc validate                                              # Check project structure
fcc simulate --scenario GEN-001                           # Run simulation
fcc generate-docs --dir ./docs --personas all             # Generate all 1,348 doc files
fcc generate-docs --dir ./docs --personas core            # Generate core persona docs only
fcc validate-docs --dir ./docs                            # Validate generated docs
fcc sitemap --dir ./docs                                  # Generate SITEMAP.md

Phase Roadmap

Phase	Status	Tests	Description
1. Foundation	Done	3	Project skeleton, packaging, smoke tests
2. Core FCC	Done	43	Personas, workflow graph, registry
3. Simulation	Done	32	Engine, traces, AI client, scenarios
4. Scaffolding CLI	Done	22	fcc init, templates, project config
5. Governance	Done	21	Tags, quality gates, compliance
R.I.S.C.E.A.R. Expansion	Done	259 total	Full 10-component spec, dimensions, strategic architecture
Extended Persona Gallery	Done	693 total	24 personas, cross-reference matrix, champion architecture, docs-as-code (1,348 files), dynamic validation
CI/CD, Scenarios & Docs	Done	726 total	GitHub Actions CI/CD, MkDocs deployment, 11 advanced scenarios, 5 new validation rules, comprehensive documentation
Coverage Push to 100%	Done	757 total	100% line coverage across 20 test files
Phase 5.5: Profiles & Docs UX	Done	877+ total	24 dimension profiles, documentation overhaul, MkDocs UX, 50 hand-written pages, 13 tutorials
Phase 6: Cross-Reference Expansion	Done	1030+ total	Cross-reference matrix 16→106 entries, governance/champion-of types, 3 quality gates, 9 new doc pages
Phase 7: Distribution	Done	1168 total	PyPI packaging, release automation, data relocation, _resources module, comprehensive distribution docs

Documentation Site

The FCC documentation site is built with MkDocs Material and offers 8 audience-targeted navigation paths:

Audience	Entry Point
Beginners / Students	Getting Started → Tutorials
Developers	Developer Guide
Researchers	Specification
Practitioners	Tutorials → Customization
Decision Makers	For Decision Makers
Managers / Team Leads	For Teams
Content Strategists	Personas → Specification
Open Source Contributors	Developer Guide → Contributing

Next Steps

• Advanced Automation (Phase 8) — Custom persona templates, plugin system, template marketplace
• Agent-Human Collaboration (Phase 9) — Feedback loop instrumentation, human-in-the-loop handoff protocols
• Scaled Agile Integration (Phase 10) — Architectural runway management, portfolio-level orchestration

Documentation

• QUICKSTART.md — 60-second getting started guide
• ARCHITECTURE.md — Detailed module walkthrough, data flow, and design decisions
• CONTRIBUTING.md — How to add personas, scenarios, templates, and more
• GLOSSARY.md — Comprehensive glossary of FCC terms and all 24 personas
• CHANGELOG.md — Release history and notable changes
• ROADMAP.md — Project roadmap and future milestones
• STRATEGIC_ARCHITECTURE_REVIEW.md — Cross-project alignment and canonical authority

Contributing

Contributions are welcome! Whether you are fixing a bug, adding a persona, improving documentation, or proposing a new feature, we would appreciate your help. Please read the CONTRIBUTING.md guide for development setup, code style, testing requirements, and the pull request process.

License

MIT License. Copyright (c) INFORMATION COLLECTIVE, LLC. See LICENSE for details.