Skip to content

Getting Started (Coordination Stewards)

This page is a zero-prerequisite orientation for coordination stewards. You will not write any code, and you will not open a pull request. By the end you will have (a) a mental model of what the docs/ecosystem/coordination/ subdirectory is, (b) a reading path through the four files it contains, and (c) a checklist for your first steward-relevant conversation with an FCC contributor.

The one-minute summary

The docs/ecosystem/coordination/ subdirectory contains four files: a landing README.md and three sibling records, one per ecosystem authority. Each sibling record is a living document that captures the current state of FCC's coordination with that authority — cadence, handoff artifacts, cross-repo contracts, open items, and references.

docs/ecosystem/coordination/
├── README.md                                    # landing + shared format template
├── nexus-research-coordination.md               # NEXUS (research + JV)
├── phoenix-open-science-coordination.md         # PHOENIX (open-sci + IP)
└── orchestra-integration-tests-coordination.md  # ORCHESTRA (contract tests)

Every sibling record conforms to the same six-section skeleton: Authority role, Coordination cadence, Handoff artifacts, Cross-repo contracts, Open items, References. That shared shape is load-bearing — it means an external reader, a new persona, or a future authority can read all three in parallel and compare them line-by-line.

First reading path

Give yourself 60–90 minutes for the first read. Do it in this order:

  1. README.md — start here. The landing page explains why the subdirectory exists, what the shared template looks like, and who each sibling record targets. Read it fully.
  2. nexus-research-coordination.md — read this next. NEXUS is the simplest of the three because it has a single FCC-side owner (RHL) and a narrow scope (academic papers + JV convening + registry mirror).
  3. orchestra-integration-tests-coordination.md — read this third. ORCHESTRA is the only fully public project in the ecosystem at v1.7.1, which makes it the easiest to validate against live state (you can clone the test repo and run the suite).
  4. phoenix-open-science-coordination.md — read this last because it has three tracks under one authority (open-science validation + patent/IP consolidation + 58-gate quality registry), each with its own owner-persona and lifecycle. It is the most complex sibling.

The mental model

Picture the FCC repository as a box with three doors:

  • Research door — things pass through it toward NEXUS. The key is held by RHL. The lock is peer-review and JV-partner coordination.
  • Open-science door — things pass through it toward PHOENIX. The key is held by OSC (open-sci), IHL (patent), or PCT (claim matrix), depending on the artifact. The lock is owner-approval plus (for patent artifacts) counsel acknowledgement.
  • Integration-tests door — things pass through it toward ORCHESTRA. The key is held by LAR and OTO. The lock is the offline contract suite — if the suite is green, the door is open.

Each coordination record describes its door — what it looks like, what passes through it, who holds the key, what breaks if the lock is bypassed. As a steward you do not hold any of the keys. Your job is to make sure the description of each door is accurate, up-to-date, and readable.

Key objects you will encounter

  • Authority record (Markdown) — one of the three sibling files. Has YAML front matter (title, authority, scope, version, last_updated) and six H2 sections.
  • Owner persona — the FCC-side persona responsible for a given handoff lane. Listed by ID (RHL, IHL, OSC, PCT, LAR, OTO) in the record header and cross-referenced in the authority's own persona YAML under src/fcc/data/personas/.
  • Confidentiality tier — applied per-track. Open-science and integration-tests are public by default; patent-lane artifacts are counsel-gated until FTO clearance.
  • Handoff artifact — anything that crosses an authority boundary. Papers, reproducibility manifests, patent disclosures, contract tests.
  • Drift CI — the automated check that verifies parity between a vendored mirror (FCC side) and an authoritative source (authority side). SHA-256-based for registries; source-tree-walking for contract surfaces.

A small worked example

Imagine FCC ships a new persona called PatentDraftDiagramReviewer whose responsibilities include reviewing USPTO-style figures before a provisional filing. This new persona touches all three authorities:

  • NEXUS — if any paper (quantum-locality, Zachman-R.I.S.C.E.A.R.+SAFe) depends on the diagrams, the record needs a note that PatentDraftDiagramReviewer is now in the loop between architectural evidence and paper handoff.
  • PHOENIX — this is the primary authority. IHL opens a coordination-record amendment in phoenix-open-science-coordination.md under Cross-repo contracts > Track 2 — Patent / IP consolidation. The Open items section gets one new row.
  • ORCHESTRA — the persona adds to the 168-persona count; contract test test_plugin_discovery.py gets a new assertion. orchestra-integration-tests-coordination.md needs a single-line update in Handoff artifacts (persona count).

A coordination steward reviews all three proposed amendments in one pass and either approves them or pushes back for clarity. That is the job.

What you can ask an FCC contributor

Here is a ready-made checklist of questions that produce steward-useful answers:

  1. "Which of the three authorities does this change cross?"
  2. "Who is the FCC-side owner persona for the lane?"
  3. "What is the confidentiality posture — public, counsel-gated, or owner-approval-gated?"
  4. "Does this change require an amendment to one or more coordination records? If so, which sections?"
  5. "Is the last_updated date in the front matter still accurate after your change?"
  6. "Does the change introduce a new handoff artifact, and if so, is it in the record's cross-repo contracts table?"

What you should not worry about (yet)

  • Patent strategy. That is counsel's domain; the steward captures the decision, not the reasoning.
  • Test implementation. ORCHESTRA test authoring is the owner-persona's responsibility; the steward captures the contract shape, not the assertions.
  • Venue-selection calls. RHL coordinates venue with NEXUS; the steward captures the queued venues in the record's cadence section.

Where next

Proceed to Reading Coordination Records for a section-by-section reading guide, or skip ahead to Writing New Coordination Records if a fourth authority is imminent and you need the shared-format template immediately. For lane-specific flows, the three walkthroughs (NEXUS, PHOENIX, ORCHESTRA) are independent — read whichever is currently in front of you.