Skip to content

LYRA Integrator — Evolution Guide

Introduced in v1.6.0. LYRA Integrator is a JV collaboration role with FCC phase Build, Zachman cell DESIGNER/HOW, and archetype The Bridge Builder. This guide distils the role charter into an actionable evolution path: where the role sits in its career track, the technical and behavioural milestones to hit in the first 180 days, a concrete 90-day onboarding playbook, the pitfalls most commonly encountered, and the escalation routes when the role reaches the edge of its charter.

Consult the complementary references:

Role snapshot

Field Value
Full title LYRA Integrator
Category jv_collaboration
FCC phase Build
Zachman cell DESIGNER/HOW
Archetype The Bridge Builder
Introduced v1.6.0
Collaborators 5 (upstream: 2, peer: 1, downstream: 2)

Consumer-project engineer who integrates the LYRA bridge into new projects. Translates between the project's domain model and the LYRA stable contract, owns client-side retry/backoff discipline, surfaces drift signals back to the LYRA core team, and produces integration playbooks that other downstream projects can reuse.

Career Path

Where this persona sits. Application engineer → API integration specialist → Cross-project bridge integrator. In FCC, this role carries the Zachman cell DESIGNER/HOW, which places it in the designer perspective; the column (how) indicates its primary column affinity with process, mechanism, and interface design. The role sits in the jv_collaboration category and operates predominantly in the Build phase of the FCC workflow.

Specialties that feed in. REST/gRPC/GraphQL client design, SemVer discipline, backward-compatible migration authoring, integration-test architecture, client-side observability (tracing, metrics), and a tolerance for cross-project async communication. Practitioners typically arrive with 3–7 years of experience in one or more of these specialties before assuming this role; the archetype The Bridge Builder recurs in several adjacent FCC personas (see ../archetype-atlas.md for the full archetype-to-persona map).

Advancement. Promotion to Cross-Project Integration Champion (orchestrates lyra-integrator, RHL, IHL) or cross-ecosystem bridge-steward. The conventional promotion signals are: (1) cited in three or more downstream role_collaborators lists; (2) repeated citation at the head of cross-reference traversal chains; (3) outputs consumed by at least two FCC phases. See ../evolution-pathways.md#champion-promotion-patterns for the full Champion promotion ladder.

Lateral moves. The role shares archetype The Bridge Builder with other integration-oriented personas; a lateral move preserves the archetype identity while shifting category. Conversely, a move to a Champion role is one-way — once promoted the role acquires orchestration responsibilities on top of the archetype's core behaviour.

Skill Milestones

Milestones are stated as observable markers at four checkpoints. The 30/60/90 cadence maps to the standard FCC onboarding rhythm (foundational → structured → semantic); the 180-day checkpoint corresponds to the federated stage for this role.

30-day markers

  • Complete orientation: read the LYRA bridge stable contract and the v1.5.0 promotion migration guide end-to-end.
  • Produce a "hello-LYRA" integration that exercises the 3 most common API surfaces.
  • Shadow at least one RHL research-handoff cycle and one KGSE promotion cycle.
  • Identify the one discernment trait where your starting score is lowest and document a 60-day plan to improve it.

60-day markers

  • Deliver your first independent artefact: a full integration in a target consumer project, passing the LYRA conformance suite.
  • Add at least one resilience feature (retry, circuit breaker, fallback) and one observability feature (span, metric, log) to the integration.
  • Demonstrate facility with fcc.api.lyra client conventions, SemVer-aware dependency pinning, and integration-test authoring; contribute a tool-chain improvement.
  • Attend one JV governance sync and one ecosystem integration review to understand cross-project touchpoints.

90-day markers

  • Own the LYRA integration lifecycle in at least one consumer project end-to-end.
  • Publish a retrospective documenting what you learned about the integration constraints.
  • Mentor the next adopter of the role — pair-review their first integration.
  • Refine your discernment-matrix self-ratings and request peer validation.

180-day markers

  • Carry full accountability for the role across at least one full release cycle (zero breaking-change regressions).
  • Propose at least one refinement to the LYRA stable contract based on observed gaps.
  • Represent the role in cross-ecosystem syncs and become the recognised escalation contact.
  • Score "scored" on all six discernment traits with differentiated rationale.

Core technical skills:

  • LYRA stable-contract literacy + SemVer discipline
  • Client-side resilience patterns (retry, circuit breaker, bulkhead)
  • Integration-test authoring (conformance suite, replay)
  • Client-side observability (tracing, metrics, structured logs)
  • Migration-guide authoring for consumer projects

First 90 Days

A concrete onboarding playbook for the first three months in the role.

Week 1 — Orient

  • Read the LYRA bridge stable contract at src/fcc/integrations/lyra/ end-to-end.
  • Read ../evolution-pathways.md to understand where you sit in the four-stage maturity model.
  • Read ../archetype-atlas.md#bridge-builder for the archetype pattern.
  • Read the v1.5.0 release notes for the LYRA bridge promotion story.

Weeks 2–4 — Produce the first deliverable

Your first deliverable should be aligned with the role's primary expected output: a working LYRA integration in a consumer project, backed by a conformance-suite pass and a migration guide for contributors.

Weeks 5–8 — Learn the toolchain

Develop working fluency with:

  • LYRA stable-contract literacy + SemVer discipline
  • Client-side resilience patterns (retry, circuit breaker, bulkhead)
  • Integration-test authoring (conformance suite, replay)
  • Client-side observability (tracing, metrics, structured logs)
  • Migration-guide authoring for consumer projects

Pair with a seasoned Bridge Builder practitioner for at least two sessions to absorb idiom and discipline.

Weeks 9–12 — First review

By day 90 you should have:

  • Delivered at least two artefacts that pass the role's adoption checklist.
  • Completed a peer review cycle with both upstream and downstream collaborators.
  • Documented a short retrospective on the integration constraints and how you honoured them.
  • Earned scored entries on at least three of the six discernment traits.

Adoption-checklist targets to hit by day 90:

  • Every consumer project pins to a specific LYRA SemVer range.
  • Integration passes the LYRA conformance suite on every CI run.
  • Drift signals (breaking-change warnings, SemVer gaps) surface in weekly review.
  • Migration guide covers the v1.5.0 → v1.7.0 upgrade path.

Common Pitfalls

Failure modes specific to this role, drawn from observed integration cycles across v1.5.0–v1.6.2.

Role-specific pitfalls

  • Depending on a preview-namespace symbol in production code (bypasses the KGSE promotion contract).
  • Skipping the conformance suite because "it worked last week."
  • Absorbing LYRA-side drift silently instead of surfacing a signal back to the core team.
  • Writing retry logic that masks a genuine LYRA-side incident.

Operational constraints

  • Constraint: Every integration MUST pin to a LYRA stable-contract SemVer range.
  • Constraint: Every integration MUST pass the LYRA conformance suite on CI.
  • Constraint: Every drift signal MUST surface back to LYRA via RHL / IHL handoff.
  • Constraint: No preview-namespace symbol may enter consumer-project production code.
  • Constraint: Every migration MUST carry a consumer-facing migration guide.

Discernment-trait pitfalls

Pitfalls anchored in the Discernment Matrix — each one corresponds to a trait where the role must hold a high bar:

  • Humility drift: Surfaces drift signals rather than absorbing them silently.
  • Professional Background drift: Deep API-client experience; fluent in SemVer + resilience patterns.
  • Curiosity drift: Probes every new LYRA release for breaking-change risk.
  • Taste drift: Prefers narrow, focused migrations over sweeping refactors.
  • Inclusivity drift: Authors consumer-facing docs for multiple skill levels.
  • Responsibility drift: Owns integration integrity; audit-ready conformance log.

Escalation Points

When the role reaches the edge of its charter, handoffs and escalations flow along the collaboration edges. The table below is read as: in this situation, hand off to this target with this artefact.

Collaboration graph

Upstream (this role receives from):

  • KGSE — Receives promotion notices for new stable APIs.
  • RHL — Receives research-handoff signals for new consumer scenarios.

Peers (bidirectional):

  • IHL — Coordinates on innovation-handoff cycles from LYRA to consumer projects.

Downstream (this role hands off to):

  • TLDR — Hands integration docs for three-layer reconciliation.
  • pillar-c-translator — Flags integration-doc passages needing translation.

Escalation matrix

Situation Escalate to Artefact expected
Constraint violation observed in own output Forensic Auditor (FA) evidence packet with cited constraint + remediation plan
Downstream consumer reports drift KGSE SemVer violation report + proposed migration
Cross-project handoff required RHL (research) or IHL (innovation) handoff bundle with provenance metadata
Conformance-suite regression surfaces KGSE failing conformance record + reproducer
Breaking-change window needs negotiation Release Manager (RM) impact analysis + deprecation timeline

Champion promotion. If you find yourself cited by three or more downstream personas' role_collaborators lists across consecutive releases, you may be a Cross-Project Integration Champion-promotion candidate. See ../evolution-pathways.md#when-to-promote for the formal criteria.

See also