Skip to content

ADR-001: Book Series Structure

Date: 2026-03-29 Status: Accepted

Context

The FCC framework has grown to include 84 core personas, 6 subsystems, 10 plugin types, protocol integration (A2A, MCP, AGENTS.md), knowledge federation, and a cross-project ecosystem of 11 projects. Existing documentation -- the 14-chapter guidebook, 12 notebooks, and inline docstrings -- serves well for reference and hands-on practice, but lacks a cohesive narrative that takes readers from first principles to enterprise deployment.

We evaluated several documentation strategies:

  1. Expand the existing guidebook. Adding more chapters to the existing guidebook would exceed 20 chapters, making it unwieldy for linear reading.
  2. Create a single comprehensive book. A single book covering beginner through advanced topics would exceed 40,000 words and require readers to skip irrelevant sections.
  3. Create a graded book series. Multiple books at increasing difficulty levels, each self-contained but building on the previous.
  4. Create a wiki. Unstructured, community-editable documentation with no prescribed reading order.

We also evaluated style approaches, drawing inspiration from production-focused AI engineering guides (e.g., Chip Huyen's "AI Engineering") that prioritize practical, example-driven, conceptual content over exhaustive API reference.

Decision

We will create a 3-book series with 24 chapters total, following a production guide style:

  • Book 1: Understanding FCC (Beginner, 8 chapters, 1,000--1,500 words each). Covers concepts: the FCC cycle, R.I.S.C.E.A.R., workflows, governance, collaboration, ecosystem. Ends with a hands-on getting-started chapter.
  • Book 2: Building with FCC (Intermediate, 8 chapters, 1,500--2,000 words each). Covers practice: project setup, custom personas, workflow design, simulation, plugins, event bus, collaboration sessions, production deployment.
  • Book 3: Advanced FCC (Advanced, 8 chapters, 1,500--2,500 words each). Covers architecture: semantic search, knowledge graphs, RAG, federated knowledge, protocol integration, cross-project orchestration, documentation intelligence, enterprise scaling.

Each chapter includes: title, learning objectives, substantive main content, key takeaways, and cross-references to other chapters, notebooks, guidebook sections, and ADRs.

The series is tracked by a book_series.yaml data file under src/fcc/data/docs/ for programmatic access and validation.

Consequences

Positive

  • Clear learning path. Readers can choose the book that matches their current level and read it front-to-back.
  • Manageable scope. Each book is 8,000--20,000 words, readable in a single sitting.
  • Cross-referencing. The three-book structure creates natural cross-reference opportunities between conceptual, practical, and advanced material.
  • Companion alignment. Each book chapter maps to specific notebooks, guidebook sections, and Streamlit apps.
  • Programmatic tracking. The YAML data file enables validation (all chapters exist, word counts are within range) and generation (table of contents, reading path diagrams).

Negative

  • Maintenance overhead. 24 chapters plus 3 indices is more documentation to maintain than a single guidebook expansion.
  • Potential duplication. Some concepts are introduced in Book 1 and revisited in Book 2, creating maintenance coupling.
  • Style consistency. Maintaining a consistent production-guide voice across 24 chapters requires editorial discipline.

Mitigations

  • Documentation freshness is checked in CI (see ADR-002 for code-derived docs).
  • Cross-references are validated programmatically.
  • A single book_series.yaml schema enforces structural consistency.