Metadata-Version: 2.4
Name: fcc-agent-team-ext
Version: 0.2.0
Summary: FCC (Find → Create → Critique) Agent Team Framework
Author: INFORMATION COLLECTIVE, LLC
License-Expression: MIT
Project-URL: Repository, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext
Project-URL: Documentation, https://rollingthunderfourtytwo-afk.github.io/l2_fcc_agent_team_ext/
Project-URL: Changelog, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/rollingthunderfourtytwo-afk/l2_fcc_agent_team_ext/issues
Keywords: fcc,agent,workflow,simulation,docs-as-code,personas,riscear
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: jsonschema>=4.23
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.1
Requires-Dist: anthropic>=0.18.0
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5; extra == "docs"
Requires-Dist: mkdocs-material>=9.4; extra == "docs"
Requires-Dist: mkdocs-material-extensions>=1.3; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
Dynamic: license-file

# FCC Agent Team Extension

[![PyPI version](https://img.shields.io/pypi/v/fcc-agent-team-ext)](https://pypi.org/project/fcc-agent-team-ext/)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)
![Tests: 1168](https://img.shields.io/badge/tests-1168-brightgreen)
![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen)

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

## Quick Start

### For Users

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

### For Contributors

```bash
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 |
|-----------|---------|
| **R**ole | Identity and function |
| **I**nput | Data and background information |
| **S**tyle | Tone, language, and format |
| **C**onstraints | Limitations and requirements |
| **E**xpected Output | Desired structure and detail |
| **A**rchetype | Fundamental character/persona |
| **R**esponsibilities | Duties and ethical obligations |
| Role **S**kills | Skills for job execution |
| Role **C**ollaborators | Team collaboration patterns |
| Role **A**doption 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

```mermaid
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

```bash
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](QUICKSTART.md) — 60-second getting started guide
- [ARCHITECTURE.md](ARCHITECTURE.md) — Detailed module walkthrough, data flow, and design decisions
- [CONTRIBUTING.md](CONTRIBUTING.md) — How to add personas, scenarios, templates, and more
- [GLOSSARY.md](GLOSSARY.md) — Comprehensive glossary of FCC terms and all 24 personas
- [CHANGELOG.md](CHANGELOG.md) — Release history and notable changes
- [ROADMAP.md](ROADMAP.md) — Project roadmap and future milestones
- [STRATEGIC_ARCHITECTURE_REVIEW.md](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](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](LICENSE) for details.
