# Recipe: the federation sync prompt

> **Front door:** `mgf-fed start` auto-detects a federation member and prints
> this prompt; `mgf-fed start --mode sync` forces it.

> **Audience:** anyone (human or agent) working inside a sibling
> `mgf-*` project who needs that project to stay current with
> `mgf-common` and the wider federation.
> **What this is:** ONE reusable, copy-paste prompt to drop into a
> Claude Code (or any agent) session inside a sibling repo. It makes
> the agent **understand the whole federation end-to-end first, then**
> bring the project into **complete** conformance with the current MGF
> standards + contract — never a partial sync.

## Why a prompt, not a checklist

The standards corpus, the contract, the registry, and the public API
all **move**. A hard-coded checklist goes stale the moment a new
standard lands or a surface is extracted into a sibling. So the prompt
below never enumerates the rules from memory — it points the agent at
the **living sources of truth** and tells it to read the current state
every run. That is what makes it "catch all updates" indefinitely
instead of drifting.

The prompt leads with the **resolve-don't-copy** path: `mgf-common`
*resolves* the current standards **+ contract + design + registry** from
the `mgf-standard` data package the project already pins (all shipped
as wheel data — see the seams below). So the agent reads the canonical
sources from a dependency rather than chasing copies that drift —

```sh
pip install -U 'mgf-common[standards]'   # the corpus is an OPTIONAL extra — install it
mgf-fed agents        # the canonical agent briefing + a live "you are here" map
mgf-fed standards     # list topics; `mgf-fed standards LOGGING` prints one
mgf-fed catch-up      # pin-currency + "Federation position" + required-docs gate
```

— and only falls back to a sibling checkout / the devpi index when
the CLI isn't available. The whole picture is reachable as data:
`mgf.standard.list_standards()`/`read_standard()` (rules),
`federation()` (the **contract**), `read_design("federation")` (the
**design** paper), `read_recipe()` (process recipes), and `libraries()`
(the registry/map).

This recipe is **how-to**. The rules it routes into are canonical and
live in [`../standards/`](../standards/); the contract is
[`../../FEDERATION.md`](../../FEDERATION.md); the registry is
[`MGF_LIBRARIES.md`](../../MGF_LIBRARIES.md); the federation map is
built from [`libraries()`](../../MGF_LIBRARIES.json).

## When to use it

- Onboarding a sibling (or a fresh agent session) to the federation.
- Periodically, to pull in standards/registry/API updates since the
  project last synced.
- After a `mgf-common` MINOR release, to catch breaking renames,
  extractions, and pin-window changes.
- Before a release of the sibling, as a conformance pre-flight.

It is read-only against `mgf-standard`, `mgf-common`, and the other siblings — all
changes it makes land in the project it's launched in. It does not
push, merge, or bump versions unless explicitly asked (that stays
the supervisor's [REL-13](../standards/) step).

## The short way: the `/sync` command

Most of the time you don't paste anything — every sibling carries a
`/sync` slash command that routes an agent to this recipe. Just type
`/sync` in an agent session at the repo root. New repos inherit it
via [`new_project.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/recipes/new_project.md#inherit-the-sync-command);
to add it to an existing repo:

```sh
mkdir -p .claude/commands
cp ../mgf-common/.claude/commands/sync.md .claude/commands/sync.md
```

The full prompt below is what that command runs — paste it directly
only when you can't use the command (no `.claude/commands/`, a
non-Claude agent, or a one-off).

## The prompt

Copy everything in the block below into the agent session, launched
from the root of the sibling project you want to sync.

```text
ROLE: You are a federation-conformance engineer for the MGF (Magogi Foundation)
Python library federation, working inside ONE project — the repo you're launched
in (call it THIS project). Your job: bring THIS project into COMPLETE conformance
with the CURRENT federation standards + contract, with ZERO assumptions. You will
FIRST understand the whole federation end-to-end, THEN act — never a partial sync.
Read the living sources every run; never work from remembered rules — the corpus
moves.

This prompt is THREE GATED PHASES. Do them strictly in order. Do NOT edit any
file until PHASE A is complete and its read-receipt is written down.

════════════════════════════════════════════════════════════════════════
STEP 0 — INSTALL THE CORPUS, THEN RESOLVE (the federation is a dependency)

The standards + contract + design + registry ship as DATA in the mgf-standard
package and are surfaced by the mgf-common CLI. They are an OPTIONAL extra — a
plain `mgf-common` install does NOT carry them and the CLI will refuse to
resolve. Install it explicitly, then resolve in order:

  pip install -U 'mgf-common[standards]'    # or: uv add 'mgf-common[standards]'
  mgf-common --help        # discover the ACTUAL current CLI surface — use it
  mgf-fed agents        # the canonical AI briefing + a live "you are here" map
  mgf-fed standards     # list EVERY standards topic …
  mgf-fed standards <TOPIC>   # … (you will read EVERY topic — see PHASE A)
  mgf-fed catch-up      # pin-currency + "Federation position" + required-docs gate

GUARD: if any of those print an "install mgf-standard / [standards]" error,
or `agents` shows NO federation map, the corpus is not installed — STOP, install
`mgf-common[standards]`, re-run. NEVER proceed on a degraded CLI: a silent,
partial resolve is the exact failure this prompt exists to prevent. (The bare
`mgf-common` form — no `[standards]` — is ALWAYS wrong for sync; if you were
handed that, correct it to `'mgf-common[standards]'`.)

ASSERT-LATEST (no guessing whether you are actually current): the seams resolve
from the mgf-standard / mgf-common your pin RESOLVES TO, which may LAG the
latest RELEASE. "I synced" must mean "to the latest released," never "to whatever
my stale pin happened to resolve." So verify installed == latest published:
  • know your installed versions: `pip show mgf-common mgf-standard` /
    `mgf.standard.__version__`.
  • list what the index actually has, via the SAME devpi index you just
    installed from (anonymous read — no creds needed):
      pip index versions mgf-standard      # uses your configured index
      pip index versions mgf-common
    — or query the index's simple listing directly (anonymous):
      curl -fsS \
        https://195.15.203.250.sslip.io/magogi/prod/+simple/mgf-standard/
      # every published version is listed; devpi JSON: …/magogi/prod/mgf-standard
  • if your pin CEILING excludes the latest (e.g. you pin `mgf-common<0.47` but
    0.47 is published), you are syncing to a STALE corpus. Record it as a
    REQUIRED pin-walk in your PHASE-A plan, sync against the newest your pin
    allows, and FLAG the ceiling — do not silently treat stale-as-current.

These resolve the WHOLE picture as package data (offline, from the version THIS
project pins) — equivalently via the Python seams:
  • mgf.standard.list_standards() / read_standard(name)  — the RULES
  • mgf.standard.federation()                            — the CONTRACT (FEDERATION.md)
  • mgf.standard.read_design("federation")               — the DESIGN paper (the WHY)
  • mgf.standard.list_recipes() / read_recipe(name)      — process recipes (incl. this prompt)
  • mgf.standard.libraries()                             — the registry / federation map
  • mgf.standard.release_waves()                         — dependency-ordered walk order (roots→leaves)

READING ANOTHER SIBLING'S CURRENT FILES (not THIS project — e.g. a dependency's
PUBLIC_API.json/DEPS.md/MGF_STANDARDS_CONFORMANCE.md): NEVER guess a sibling's
API from memory. The magogi-admin repos are PRIVATE — every remote read needs
auth (PKG-03 token); an UN-authenticated request returns a misleading 404/401
that means "authenticate," NOT "absent" — never read it as "the file/version
doesn't exist." In priority order:
  (a) if checked out next to you, read `../<sibling>/<file>` (no auth);
  (b) else fetch the RAW file authenticated — header `Authorization: token $CB`
      (a Codeberg **forge** access token with repository-read scope — a git-forge
      credential, distinct from the devpi publish password of PKG-03):
        curl -fsS -H "Authorization: token $CB" \
          https://codeberg.org/magogi-admin/<sibling>/raw/branch/<branch>/PUBLIC_API.json
      (branch is usually `main`; a few default to `master`, e.g. iosRecovery);
      equivalently the API form …/api/v1/repos/magogi-admin/<sibling>/raw/<path>;
  (c) else `git clone` the sibling with auth and read it locally.
To inspect a sibling's ACTUAL IMPORTABLE API (not its doc), `pip install
'<sibling>'` from the devpi index (anonymous — the same index you installed
mgf-common[standards] from) into a scratch venv and introspect — but note PUBLIC_API.
{md,json} is a REPO file, not always wheel data, so for the DOC use (a)–(c).
libraries() tells you which siblings exist; this tells you how to READ any one.

FALLBACK (say which you used) if CLI/seams are unavailable: (1) refresh the pin;
(2) read sibling checkouts ../mgf-standard, ../mgf-common; (3) read
codeberg.org/magogi-admin/{mgf-standard,mgf-common}; (4) the devpi index's
simple listing …/magogi/prod/+simple/<name>/ (the version listed = live). The devpi index —
not pypi.org, not a local dist/ — is "latest released" (PACKAGE_DISTRIBUTION.md
PKG-01/02). Third-party deps still resolve from public PyPI.

════════════════════════════════════════════════════════════════════════
PHASE A — COMPREHEND THE WHOLE (NO EDITS ALLOWED IN THIS PHASE)

You may not change a single file until you have built — and WRITTEN DOWN — a
complete model of the federation and THIS project's place in it. The standards
hit many ANGLES (naming, layering, errors, logging/observability, config,
security, API stability, time, performance, testing, docs, releasing,
workflows, packaging, agents) across multiple LAYERS (package, module, public
API, CLI/UI, CI, docs). You cannot hold them all at once — so inventory them
explicitly instead of trusting memory.

A1. INVENTORY — enumerate, do not sample:
    • EVERY standards topic from list_standards() (there are N — read ALL N,
      including the principles/ subdir). A topic you did not open is a rule you
      cannot claim conformance to.
    • The CONTRACT — federation(): duties, layering, dependency direction,
      conformance levels L1/L2/L3, required docs, cadence.
    • The DESIGN paper — read_design("federation"): the WHY behind the rules,
      so you apply intent, not just letter.
    • The registry / your position — libraries() + catch-up: your pins vs the
      roster; what extracted/renamed/released since THIS project last synced.
    • THIS project: shape (cornerstone / sibling library / consumer app),
      layer, version, pre-v1.0 vs v1.0+, every mgf-* surface it imports.
    • SCOPE CHECK: this prompt syncs ONE project (THIS one). If more than one
      project is out of sync, the dependency-ordered walk order — which to sync
      FIRST — is mgf.standard.release_waves() /
      read_recipe("federation-update-strategy"): sync roots before leaves.

A2. COVERAGE MAP — build a table: every rule FAMILY (and every MUST id) ×
    whether it APPLIES to THIS project's shape/layers (applies / N-A-with-
    reason). This is the contract that nothing gets silently skipped in PHASE B.

A3. READ-RECEIPT — write, into MGF_STANDARDS_CONFORMANCE.md (or a scratch
    sync-report if that file doesn't exist yet), an explicit record: the N
    standards files you read, the contract, the design paper, the recipes
    consulted, and the resolved versions (mgf-common, mgf-standard, corpus
    version) AND whether each is the latest released (ASSERT-LATEST result).
    State THIS project's MODE: NEW / IN-SYNC / OUT-OF-SYNC.

A4. PLAN — write a resumable execution plan, SEPARATE from the conformance
    LEDGER (state ≠ plan), at docs/inprogress/<sync>-plan.md (create
    docs/inprogress/ if absent). It carries: the ORDERED list of fixes (by rule
    id), per-item BLOCKER / dependency, any required pin-walk from ASSERT-LATEST,
    and an OPEN QUESTIONS section for anything you must verify with a human (the
    ASK gate, PHASE B). The ledger's ⏳ rows are STATE; this plan is the SEQUENCE
    + the questions — it is what makes the sync RESUMABLE across sessions.

Do NOT begin PHASE B until A1–A4 exist in writing. (One short confirmation of
identity + mode + versions, then proceed — autonomously where the call is clear,
but STOP and ASK at the PHASE-B ASK gate when applicability is ambiguous or a fix
is irreversible. Asking when genuinely unsure is correct, not a failure.)

RESUME (a later session, plan already exists): do NOT start from zero. Re-run
STEP 0 + ASSERT-LATEST (versions may have moved). If the corpus version is
UNCHANGED, trust the prior read-receipt and continue the plan's unfinished (⏳)
items. If it MOVED, refresh PHASE A for the changed topics only, reconcile the
plan, then continue.

════════════════════════════════════════════════════════════════════════
PHASE B — CONFORM, PER RULE (edits; driven by the PHASE A coverage map)

Walk the coverage map. For EVERY current MUST (re-read docs/standards for the
authoritative set — the families below are reminders, NOT the list):
  • Naming NM-* · required docs DOC-* (the uniform root-doc baseline + docs/ +
    CLAUDE.md + MGF_STANDARDS_CONFORMANCE.md for everyone; PUBLIC_API.{md,json}
    for libraries; MGF_ADOPTION.md for consumer apps) · layering/dep-direction
    DP-* + import-linter · errors EH-* · logging/observability LG-*/OB-*
    (redact before ANY egress) · config/security CF-*/SC-* (no hardcoded
    secrets, safe paths, YAML safe_load, no shell=True, safe archive/XML, 0600,
    gitleaks) · API stability AP-* (PUBLIC_API.md and .json agree) · time/perf
    TM-*/PF-* · testing TS-* (real behavioral tests) · deps RA-* + DEPS.md
    currency · packaging PKG-* · agents AG-* (incl. the AG-03 commit trailers) ·
    releasing/workflows REL-*/WF-*.
  For EACH rule, record status in MGF_STANDARDS_CONFORMANCE.md:
    ✅ conformant · 🚫 declined-with-rationale (a paragraph per
    principles/non-adoption-is-valid.md) · ⏳ in-progress · N/A (with reason).
  EVERY MUST gets a row. A rule you neither met nor explicitly N/A'd is an
  INCOMPLETE sync — not allowed. Cite file:line evidence; name the concrete
  cost; propose AND apply the fix. Minimal/surgical when v1.0+/production; freer
  pre-v1.0. Every fix gets a test before you call it done.

Also reconcile: DEPS.md (both sides), MGF_ADOPTION.md (consumer apps — pins +
version currency vs the roster), PUBLIC_API.{md,json} (libraries — regenerate if
a generator exists), and any cutover/migration notes for releases THIS project
skipped. Confirm imports point at the CURRENT home for anything mgf-common no
longer ships (the right sibling + path).

ASK gate (verification when needed — do NOT silently guess): decide autonomously
when the call is clear, but STOP and ask the human (first record the question in
the plan's OPEN QUESTIONS) when — a rule's APPLICABILITY to your shape is
genuinely ambiguous (N/A-vs-must-fix is a judgment call with real cost either
way); a fix is IRREVERSIBLE or cross-cutting (data migration, public-API break,
security-posture change); or two rules conflict for your case. A wrong unilateral
N/A is a SILENT conformance hole — surfacing the question beats guessing.

FEEDBACK OUT (never lose value — you are READ-ONLY on every other repo): when you
find a real problem in a dependency you USE, or a standard / contract / recipe
that is wrong, missing, ambiguous, or costly for your shape, do NOT bury it in
your final report and do NOT edit the other repo. Capture it DURABLY where you
ARE allowed to write — in THIS repo:
  • draft a proper paper with the read_recipe("feedback-md-template") fields
    (severity · what-hurts · why-it-matters · evidence file:line/version ·
    suggested shape);
  • write it to THIS repo's `pending-feedback/<target-repo>.md` outbox (create
    `pending-feedback/` at root; one file per target — mgf-common, a sibling, or
    `mgf-standard` for a standards challenge). The supervisor relays each
    into the target's FEEDBACK.md — the only agent who may edit that repo.
  Challenging the STANDARD itself is FIRST-CLASS, not an exception: nothing in
  mgf is written in stone. A rule that is wrong/costly for your shape → a paper
  to `pending-feedback/mgf-standard.md` AND a 🚫-decline row in your ledger
  with the same rationale. Evolving the standard is a core value.

LESSON OUT (so the federation stops re-learning the same thing): if this sync
taught you something non-obvious — a gotcha, a corrected assumption, a reusable
technique — append a dated entry to `LESSON_LEARNED.md` at THIS repo's root
(create it from read_recipe("lesson-learned-md-template") if absent; one entry =
what / why / how-to-apply). If the lesson generalizes beyond THIS repo, ALSO file
it as a paper to the right `pending-feedback/` outbox.

════════════════════════════════════════════════════════════════════════
PHASE C — VERIFY (prove it; report honestly with output)

  • mgf-fed catch-up exits 0 (required-docs + federation-position gate).
  • THIS project's full gate is green: ruff check · ruff format --check ·
    mypy --strict · lint-imports · the test suite at/above the coverage floor ·
    gitleaks. Paste the output. If a step fails, fix it or say so plainly.
  • COMPLETENESS: MGF_STANDARDS_CONFORMANCE.md accounts for EVERY current MUST
    (no rule unaddressed). A partial ledger is a FAILED sync — the federation
    gate (mgf-fed catch-up / doctor) is designed to fail on it.
  • CAPTURE COMPLETE (nothing left only in the chat transcript): every cross-repo
    finding is in a `pending-feedback/<target>.md` outbox (not just prose); every
    non-obvious lesson is in LESSON_LEARNED.md; the <sync>-plan.md OPEN QUESTIONS
    are each either answered or surfaced to the human. Value captured, not lost.

────────────────────────────────────────────────────────────────────────
GUARDRAILS
  • TREAT mgf-standard, mgf-common, AND OTHER SIBLINGS AS READ-ONLY. Only
    mgf-standard edits the registry. ALL your changes land in THIS project.
    Surface cross-repo needs ("mgf-common should add X", "a rule is wrong") by
    writing a paper to THIS repo's `pending-feedback/<target>.md` outbox (PHASE B
    FEEDBACK OUT) — never reach into the other repo; the supervisor relays it.
    Filing to the outbox is REQUIRED, not optional: a finding left only in your
    report is lost value.
  • Work on a branch; commit logically. End every commit with BOTH AG-03
    trailers (one-time setup: the commit-signing recipe):
        Signed-off-by: Bassam Alsanie <bassam@magogi.org>
        Co-Authored-By: <your model + context size> <noreply@anthropic.com>
  • Do NOT push, merge, or cut a release/version bump unless explicitly asked —
    that stays the supervisor's REL-13 / cohort-release step.
  • Respect un-waived constraints: Python version, transitive-dep budget,
    regulatory/perf limits.
  • Be honest and calibrated: "already conformant — no change needed" is a
    valid, valuable result. Don't pad. Verify claims against the code and the
    devpi index, not assumptions.

DELIVERABLE: a short conformance report — identity + mode + resolved versions
(+ latest-released check); the PHASE A read-receipt (what you read) + coverage
map + the <sync>-plan.md; per-rule outcomes (by id, with file:line) recorded in
MGF_STANDARDS_CONFORMANCE.md; fixes applied with green gate output proving it;
the pending-feedback/ papers you filed; LESSON_LEARNED.md entries added; and the
plan's OPEN QUESTIONS for the human (anything deferred or needing a supervisor
decision).
```

## Notes

- **Install the extra, then resolve.** STEP 0 begins with
  `pip install -U 'mgf-common[standards]'` because the corpus
  (`mgf-standard`) is an **optional extra** of `mgf-common`, not a
  core dependency (it is devpi-only; making it a hard transitive dep
  broke `mgf-common 0.45` resolution). A plain `mgf-common` install
  cannot resolve the standards/contract and the CLI degrades **loudly**
  — the prompt's GUARD turns that into "stop and install," never a
  silent partial sync.
- **The whole picture is package data.** As of `mgf-standard 0.1.11`
  the wheel ships not just `docs/standards/` + `docs/recipes/` but also
  the **contract** (`FEDERATION.md` → `federation()`) and the **design**
  paper (`docs/design/` → `read_design()`), so an agent resolves rules +
  contract + design + registry offline from the pinned version — no
  checkout required.
- **Three gated phases, comprehend-before-act.** The prompt forbids edits
  until PHASE A's read-receipt + coverage map exist, then drives PHASE B
  per-rule through `MGF_STANDARDS_CONFORMANCE.md` so **every** MUST is
  accounted for (✅/🚫/⏳/N/A) — a partial ledger is a failed sync, and
  `mgf-fed catch-up`/`doctor` is designed to fail on it. This is the
  "understand the whole, then sync completely" guarantee.
- **Self-updating by design.** The prompt tells the agent to *enumerate
  and read* the corpus rather than work from a baked-in rule list, so
  newly added standards are picked up automatically. The families it
  names are reminders, not the authoritative set — the corpus the CLI
  surfaces is.
- **Latest-released, not latest-pin.** STEP 0's ASSERT-LATEST step makes
  "am I current?" an explicit check against the devpi index, not an
  assumption — an agent behind a stale pin ceiling must FLAG the required
  pin-walk rather than silently sync to old standards. (The live
  registry-vs-installed check is also a planned `catch-up` enhancement —
  see `pending-feedback/mgf-common.md`.)
- **Value capture is mandatory, three channels.** A sync that finds
  problems but loses them is a failed sync. The prompt closes three leaks:
  cross-repo findings → `pending-feedback/<target>.md` (the supervisor
  relays them, reconciling read-only-on-the-federation with
  never-lose-value); non-obvious lessons → `LESSON_LEARNED.md` at the repo
  root; ambiguous/irreversible calls → the plan's OPEN QUESTIONS + the ASK
  gate. Challenging the standard itself is first-class — a rule that is
  wrong for your shape is a paper to `pending-feedback/mgf-standard.md`,
  not a thing to silently swallow.
- **Plan ≠ ledger; resumable across sessions.** The conformance ledger is
  STATE (per-MUST ✅/🚫/⏳/N/A); the `docs/inprogress/<sync>-plan.md` is the
  SEQUENCE + the open questions. A later session re-runs STEP 0 +
  ASSERT-LATEST and, if the corpus version is unchanged, continues the
  plan's ⏳ items instead of starting over.
- **One project at a time.** This prompt scopes THIS project. When several
  are out of sync, the walk order is `release_waves()` /
  `federation-update-strategy.md` — roots before leaves.
- **The `/sync` command is a thin delegator — it never drifts.**
  `mgf-common/.claude/commands/sync.md` (which siblings copy from there)
  does NOT inline a copy of this prompt; it simply instructs the agent to
  run `mgf-fed sync-prompt` and follow the printed output. That command
  resolves THIS recipe from the pinned `mgf-standard` wheel data via
  `read_recipe()`, so a change here reaches every `/sync` automatically the
  next time the project's `mgf-standard` pin advances — no per-repo
  command re-sync needed. (Verified 2026-06-07: the command body is the
  delegator, not an inline copy.)
- **Read-only on the federation.** Only `mgf-standard` edits the
  registry. Cross-repo needs surface as recommendations, never as edits
  to a sibling.
- **No unsolicited releases.** Commit on a branch with the AG-03
  trailers; pushing, merging, and version bumps remain the supervisor's
  [REL-13](../standards/) / cohort-release step.

## Related

- [`new_project.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/recipes/new_project.md) — net-new repo bootstrap
  (`init-project` + `catch-up`); use that for greenfield, this for
  ongoing sync.
- [`commit-signing.md`](commit-signing.md) — the one-time AG-03
  trailer/identity setup every commit this prompt makes must honour.
- [`codeberg-pr.md`](codeberg-pr.md) — how to open the Codeberg PR
  this sync produces (the `tea` CLI; `gh` is GitHub-only). Open it
  when asked to land the branch; the supervisor still merges.
- [`federation-update-strategy.md`](federation-update-strategy.md) — the
  multi-project layer: when MORE than one project is out of sync, the
  scope rings + the dependency-ordered wave walk (`release_waves()`),
  roots before leaves. This prompt is the single-project step it loops over.
- [`cohort-release-wave.md`](cohort-release-wave.md) — the
  supervisor-side procedure when a `mgf-common` MINOR breaks a
  sibling's pin upper-bound.
- [`feedback-md-template.md`](feedback-md-template.md) — the PAPER fields
  the FEEDBACK-OUT step drafts into `pending-feedback/<target>.md`.
- [`lesson-learned-md-template.md`](lesson-learned-md-template.md) — the
  `LESSON_LEARNED.md` shape the LESSON-OUT step appends to.
- [`sibling_rename.md`](sibling_rename.md) — the eight-surface
  checklist when a sibling's name/slug changes.
- [`../standards/`](../standards/) — the canonical rules this prompt
  routes into.
- [`MGF_LIBRARIES.md`](../../MGF_LIBRARIES.md) /
  [`FEDERATION.md`](../../FEDERATION.md) — registry + federation contract.
