Skip to content

Chapter 27: The Developer Journey

New in v1.3.10. This chapter traces the full developer-adoption journey through FCC — from first install through writing a custom plugin to contributing upstream. Earlier chapters covered the parts of the framework (personas, workflows, plugins, events); this chapter covers the person who assembles those parts into shipping software.

Why a developer-journey chapter

Documentation written module-by-module answers "what does this do?" but is a poor fit for "I am a developer who wants to ship X, what is the shortest path?" That is the question this chapter answers. It is the developer's version of the persona-evolution lifecycle — DRAFT, FOUNDATIONAL, STRUCTURED, SEMANTIC, FEDERATED — except the stages now describe the developer's relationship with FCC rather than a persona's relationship with the registry.

The journey has five phases: Discovery, Install, Run, Extend, Contribute. The diagram below shows the phases and the typical artifacts produced at each stage.

flowchart LR
    D[Discovery<br/>~1 day] --> I[Install<br/>~30 min]
    I --> R[Run<br/>~2 hours]
    R --> E[Extend<br/>~2 weeks]
    E --> C[Contribute<br/>~1 month+]

    D -.->|artifact| DA[bookmark, issue, star]
    I -.->|artifact| IA[working .venv + fcc --version]
    R -.->|artifact| RA[first simulation trace]
    E -.->|artifact| EA[custom persona + plugin]
    C -.->|artifact| CA[merged PR + upstream change]

Phase 1 — Discovery (~1 day)

Discovery is everything a developer does before running pip install. It is almost entirely a documentation problem. The reader has arrived from GitHub, a talk, a blog post, or a colleague's recommendation and needs to answer three questions in order:

  1. What does this do?
  2. Does it solve my problem?
  3. Is it worth my time?

The FCC documentation answers these through three entry points:

The reader who completes Discovery has bookmarked two pages, scanned one tutorial, and either decided to continue or closed the tab. The documentation's job is to make that decision quick and honest.

Signals that Discovery succeeded

  • The developer files a GitHub star or a bookmark — measurable.
  • The developer runs pip install within 48 hours — measurable.
  • The developer drops a question in Discussions — measurable.
  • The developer forgets they bookmarked — the silent failure mode.

Phase 2 — Install (~30 min)

Install is the first commitment of time. Friction here costs more than friction anywhere else because the developer has no sunk cost and can bail with zero regret. FCC's install surface is deliberately minimal:

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
fcc --version

Five commands. If any of them fail, the developer is in the wrong state and the docs need a troubleshooting path. Getting Started — Troubleshooting covers the known failure modes.

The mock-first commitment

A recurring theme across the install and run phases is that FCC works offline by default. No API keys, no network calls, no containers. This is a deliberate design choice, documented in ADR-004 — Embedding Provider Protocol, because a developer who has to configure an LLM before seeing a result will bail.

The mock simulation engine at src/fcc/simulation/engine.py produces realistic traces using deterministic stubs for every persona. The traces are good enough to write extension code against — which is how most developers reach the Run phase without ever touching an API.

Phase 3 — Run (~2 hours)

Run is where the developer produces their first artifact. FCC's canonical first artifact is a simulation trace.

fcc simulate --scenario find-create-critique-cycle --out /tmp/trace.json
fcc dashboard simulation --trace /tmp/trace.json

Two commands. The first runs the mock simulation for the canonical Find → Create → Critique scenario. The second opens the CLI dashboard on the trace. The developer now has:

  • A JSON trace at /tmp/trace.json
  • A list of persona-by-persona contributions
  • A set of quality-gate pass/fail lines
  • A score distribution per phase

From here, the three-fork decision tree diverges by developer type.

flowchart TD
    T[First trace complete] --> Q{What's next?}
    Q -->|Build an app| A[Use FCC as a library]
    Q -->|Integrate a workflow| W[Customise scenarios]
    Q -->|Extend the framework| X[Write a plugin]

    A --> A1[Notebook 01 + 02]
    W --> W1[Scenario editor + YAML]
    X --> X1[Plugin dev guide]

Notebook-first path

Notebook-first developers open notebooks/01_fcc_fundamentals.ipynb and step through the cells. The notebook wraps the CLI in a Python API, so the developer learns PersonaRegistry, SimulationEngine, and ActionEngine through executable cells rather than source reading. This path is optimal for data-science-adjacent developers.

Scenario-first path

Scenario-first developers copy src/fcc/data/scenarios/find-create-critique-cycle.json to ./scratch/my-scenario.json and edit it. The scenario schema is strict but small — the developer is usually writing their first custom scenario within an hour. This path is optimal for integration engineers with an existing workflow to port.

Plugin-first path

Plugin-first developers go straight to docs/developer/plugin-development.md and the 11 plugin types. This path is optimal for developers building a commercial extension or a vertical pack — the payload is higher but so is the upfront learning.

Phase 4 — Extend (~2 weeks)

Extend is the phase where the developer commits to FCC. They have written at least one of:

  • A custom persona YAML
  • A custom scenario JSON
  • A custom plugin class
  • A subclass of ModelFacade

The canonical "you have arrived" signal is a passing quality gate on custom content. fcc validate --personas --file scratch/my_persona.yaml returning green means the developer has absorbed the R.I.S.C.E.A.R. contract, the dimensions schema, the archetype assignment rule, and the cross-reference matrix well enough to write valid content.

The Extend phase is also when the developer encounters the collaboration engine for the first time. Running a human-in-the-loop session against their custom persona is usually the moment FCC "clicks" as a framework, because they see their YAML turn into prompts, their prompts turn into turns, and their turns turn into scored deliverables.

Common Extend-phase artifacts

The Extend phase typically produces four types of artifact:

  1. Custom persona under data/personas/my-persona.yaml
  2. Custom scenario under data/scenarios/my-scenario.json
  3. Custom plugin under my_package/fcc_plugins/my_plugin.py
  4. Event subscriber for observability or audit

The plugin system has 11 plugin types: personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, subscribers, and vocabulary providers. The Extend developer usually needs 1-3 of these for their first real deployment.

Extend-phase architecture

The PlantUML diagram below shows the class relationships the Extend developer needs to internalise — how PersonaSpec, WorkflowAction, ActionEngine, and SimulationEngine fit together when they assemble a run from a persona YAML and a scenario JSON.

@startuml
skinparam monochrome true
skinparam shadowing false
skinparam packageStyle rectangle

class PersonaSpec {
  + persona_id: str
  + role_title: str
  + riscear: RISCEARSpec
  + dimensions: PersonaDimensionProfile
}

class PersonaRegistry {
  + load_default() PersonaRegistry
  + get(id: str) PersonaSpec
  + by_category(cat: str) list
}

class WorkflowAction {
  + action_type: WorkflowActionType
  + persona_id: str
  + prompt_template: str
}

class ActionEngine {
  + run(action: WorkflowAction) ActionResult
}

class SimulationEngine {
  + simulate(scenario: ScenarioSpec) Trace
  + bus: EventBus
}

class EventBus {
  + publish(event: Event)
  + subscribe(filter: EventFilter, handler)
}

PersonaRegistry o--> "*" PersonaSpec
ActionEngine --> PersonaRegistry : uses
SimulationEngine --> ActionEngine : drives
SimulationEngine --> EventBus : emits to
WorkflowAction --> PersonaSpec : references
@enduml

The daily Extend loop

The day-to-day rhythm of an Extend-phase developer looks like this:

  1. 09:00 — Pull latest main, make test on local changes.
  2. 09:30 — Add one persona field or plugin method.
  3. 10:00 — fcc validate --personas and pytest -x.
  4. 11:00 — Run fcc simulate against the extension.
  5. 14:00 — Open a scenario editor, tweak edge cases.
  6. 15:30 — fcc dashboard quality review.
  7. 16:30 — Commit with a CHANGELOG entry.

Developers who structure their day around this loop report faster quality-gate closure than developers who batch everything to end-of-sprint. The loop is the point.

Extend-phase rituals

A developer in the Extend phase benefits from three rituals:

  • Daily fcc validate — keeps the quality bar tight
  • Weekly fcc dashboard quality — surfaces drift before it compounds
  • Sprint-level model card regeneration — audit trail is free when it is automatic

Phase 5 — Contribute (~1 month+)

Contribute is the phase where the developer produces upstream change. The contribution may be a bug fix, a new plugin, a new persona, a new vertical pack, or a documentation improvement. FCC's contribution path is well-trodden:

  1. Fork on GitHub
  2. Create a feature branch
  3. Add tests first — the project runs at 99% coverage, and PRs that lower the ratio are held until they restore it
  4. Open a draft PR early for discussion
  5. Respond to review
  6. Merge, celebrate, repeat

Coverage is a hard gate: the testing coverage policy documents the ratchet mechanic — one percent per patch release from 94% to 99% over the v1.2.1 → v1.2.6 cycle. The ratchet is now at the ceiling and stays there.

The contributor constitution

Contributors operate under a lightweight constitution with three tiers:

  • Hard-stop: never break the public API without a deprecation notice in the prior minor release.
  • Mandatory: every PR has tests, a CHANGELOG entry, and passes make lint and make test.
  • Preferred: every persona-level PR includes a model card regeneration.

The constitution registry is the authoritative source for per-persona contributor behaviour.

Cross-phase anti-patterns

Four anti-patterns recur across the journey and each has a named remedy.

Anti-pattern Phase Remedy
"I'll skip the mock simulation and go straight to LLM" Run Run the mock first; compare the trace structure to LLM output before trusting the LLM
"My persona doesn't need a role_collaborators list" Extend Gate persona.role_collaborators.min_3 blocks the persona at STRUCTURED; fix it now
"I'll add a plugin to the plugins/ folder and it'll just work" Extend Plugin types are registered by entry point, not directory; follow the plugin guide
"My PR lowers coverage by 0.5%" Contribute Write the missing tests before merging; the ratchet is checked in CI

Sample-prompt cross-references

The developer journey is mirrored by a set of sample prompts that an AI pair programmer can use to accelerate each phase. Phase-specific sample prompts live at:

The journey as a maturity ladder

A clean way to think about the journey is as a maturity ladder. Each phase has exit criteria; a developer who hasn't met the exit criteria is still in the prior phase, regardless of how long they've been "around" FCC.

Phase Exit criteria
Discovery Can explain FCC to a colleague in 30 seconds
Install fcc --version returns the expected version
Run Has opened a simulation trace and read its contents
Extend Has written one of: persona, scenario, plugin, facade
Contribute Has a merged PR

Knowledge check

  1. (Short) What is the canonical first artifact of the Run phase?
  2. (Short) Name two exit criteria for the Extend phase.
  3. (Short) Which anti-pattern is the most common cause of a persona being stuck at FOUNDATIONAL?
  4. (Short) Why does FCC default to mock mode?

Answers

  1. A simulation trace (JSON) produced by fcc simulate.
  2. Any two of: custom persona YAML, custom scenario JSON, custom plugin, subclass of ModelFacade.
  3. Missing role_collaborators or incomplete R.I.S.C.E.A.R. — see ch26 for the full list.
  4. To remove the LLM-configuration barrier from the first-run experience; this is documented in ADR-004.

See also