# For AI agents (Claude, others)

> **Who you are.** You're an AI agent — either a consumer-side
> agent helping a user adopt `mgf-common`, OR the maintainer-
> side agent helping the maintainer ship releases. You need
> machine-friendly paths, the relay protocol, and the
> structured-task templates.
>
> **Start with the canonical briefing.** This document is the
> *deep* reference — the feedback-relay protocol + structured-task
> templates. The single front-door briefing every Magogi-project
> agent should read first is printed by **`mgf-fed agents`**
> (same text in [`STARTHERE.md` §"For the AI agent"](../../STARTHERE.md)).
> Read that, then this.

## In one paragraph

`mgf-common` was co-designed with AI agents as first-class
consumers. The relay process (consumer agent ↔ user ↔
maintainer agent) drives the FEEDBACK queue + cutover-guide
notifications. AI agents consume:
[`FEEDBACK.md`](../../FEEDBACK.md) §1.4 entry templates;
engineering-standards rules cited by ID (TS-19, EH-04, etc.);
per-release
[`docs/cutover/v*.md`](../cutover/) migration tables; and the
`mgf-fed standards <topic>` / `mgf-fed app-doctor` CLI
commands for in-process introspection.

## The three-actor relay (the canonical AI flow)

```
┌──────────────────┐      ┌─────────┐      ┌─────────────────────┐
│ Consumer-side    │ ───> │ User    │ ───> │ Maintainer-side     │
│ agent (Claude    │      │ (human  │      │ agent (Claude       │
│ in vm-vmanager-app /    │      │ relays) │      │ in mgf_common repo) │
│ inthewords /     │ <─── │         │ <─── │                     │
│ PlasmaMapper)    │      └─────────┘      └─────────────────────┘
│                  │
│ Files FEEDBACK   │      Maintainer triages ACCEPT / DEFER / REJECT.
│ entry; reads     │      ACCEPT → topic-batched release.
│ cutover guide.   │      Cutover guide → relayed back to consumers.
└──────────────────┘
```

The user is the **relay channel** between the two AI sides;
direct AI-to-AI communication is not part of the design. The
human stays in the loop; agents propose, the human disposes.

## Read first (paths-as-anchors)

These paths are **stable** — your prompts can hard-code them
without fragile path-resolution logic:

| Anchor | Purpose |
|---|---|
| [`FEEDBACK.md`](../../FEEDBACK.md) | The relay queue. Anchors: `#paper-NN` for individual entries. |
| [`FEEDBACK.md`](../../FEEDBACK.md) §1.4 | The entry template. Use it verbatim when filing. |
| `mgf-fed standards <TOPIC>` | The rule corpus. Cite rules by ID (e.g., "TS-19 says markers must be registered"). |
| [`docs/cutover/v<X.Y.Z>.md`](../cutover/) | Per-release migration tables. Last 3 minor versions live; older in `archive/`. |
| [`PUBLIC_API.md`](../../PUBLIC_API.md) | Full surface table. Stable layout (sectioned by module). |
| [`PUBLIC_API.json`](../../PUBLIC_API.json) | Machine-readable surface (parse this when generating code). |
| [`CHANGELOG.md`](../../CHANGELOG.md) | Per-release short-form. Cross-links to cutover guides. |
| [`docs/claude/CLAUDE.md`](../claude/CLAUDE.md) | Dense session lookup (gotchas, invariants, phase-by-phase critical facts) |

## The FEEDBACK §1.4 entry template

Use this verbatim when filing:

```markdown
#### `<TYPE>-<NN>` — <one-line title>

| Field | Value |
|---|---|
| Status | OPEN |
| Severity | 🔴 Blocker / 🟡 High / 🟢 Nice-to-have / 💭 Aspirational |
| Submitter | <consumer-project> (<phase or context>, <date>) |
| Submitted | <YYYY-MM-DD> |
| Decision | pending |
| Decided on | — |
| Scheduled for | — |
| Shipped in | — |

**Concern.** <one paragraph: what's the issue?>

**Why it matters.** <one paragraph: why this generalises beyond
just your project>

**Concrete evidence.** <code paste, file:line citations,
reproducer steps>

**Suggested shape.**

**Approach A — <name>.** <description + tradeoff>

**Approach B — <name>.** <description + tradeoff>

**Recommended:** <A or B + one-line rationale>

**Cross-references.**
- <related FEEDBACK entries by ID>
- <related cutover guide §s>

**Decision rationale.** *(Filled when triaged.)*

**Retrospective.** *(Filled when shipped.)*
```

Severity scale:
- 🔴 **Blocker** — adoption is blocked until shipped.
- 🟡 **High** — workaround exists but real friction.
- 🟢 **Nice-to-have** — quality-of-life.
- 💭 **Aspirational** — design conversation; may not ship.

## Citing rules

When recommending a change, cite the rule by ID:

> Per TS-19 (`mgf-fed standards TESTING`), all pytest markers
> must be registered in `pyproject.toml`'s
> `[tool.pytest.ini_options].markers`. Combined with TS-05's
> `--strict-markers`, this prevents typo'd markers from
> silently disabling a layer.

Don't paraphrase the rule from training data — read it from
the source-of-truth file at the cited path. The rules evolve
release-by-release; only the file is canonical.

## CLI commands you can use

In any consumer project that has installed `mgf-common`:

```bash
mgf-fed standards <topic>        # print docs/standards/<topic>.md from the wheel
mgf-fed standards web/README     # the web subtree narrative
mgf-fed standards principles/non-adoption-is-valid

mgf-fed app-doctor                   # audit the consumer project against standards
mgf-fed app-doctor --standards       # rule-by-rule conformance audit
mgf-fed app-doctor --live            # introspect a live AppContext
```

The standards are shipped as wheel data via
`[tool.hatch.build.targets.wheel.force-include]`. Reading
them via `mgf-fed standards <topic>` is faster than
fetching the Codeberg source view in many cases.

## Consumer-side AI agents (you, in a downstream project)

Your job:

1. **Audit** the consumer project's conformance: run
   `mgf-fed app-doctor` in the project root.
2. **File feedback** when a primitive's default conflicts
   with the project's deployment-coupled or policy-specific
   constraint. Use the §1.4 template.
3. **Read cutover guides** before each version bump. Per-
   consumer migration notes (named for vm-vmanager-app / inthewords /
   PlasmaMapper) often apply directly.
4. **Cite rules** when recommending refactors to the user.
5. **Stay within scope.** `mgf-fed standards SCOPE` tells you
   what mgf-common does NOT cover; don't propose it expand into
   out-of-scope territory.

## Maintainer-side AI agents (the mgf_common repo agent)

Your job:

1. **Triage** filed FEEDBACK entries (ACCEPT / DEFER /
   REJECT with rationale).
2. **Implement** ACCEPT'd entries in topic-batched releases.
3. **Ship** per the [release runbook](release.md) — version
   bump, CHANGELOG, cutover guide, build, upload, smoke
   verify.
4. **Relay notifications** — write per-consumer paragraphs
   pointing into the cutover guide.
5. **Maintain the standards** — promote patterns from
   recipe → primitive → standard when they prove themselves
   across multiple consumers.

## The "documented non-adoption" principle

When a user pushes back on adopting a primitive ("we have a
deployment constraint that conflicts with X"), don't argue
for adoption. Read `mgf-fed standards principles/non-adoption-is-valid`:
documented non-adoption is L1/L2 conformant when the rationale is
recorded. The right move is filing a FEEDBACK
entry that captures the rationale + suggests a carve-out
(LOG-01, CONFIG-01, BOOTSTRAP-01 all came from this
pattern).

## Path discipline

Always cite paths with file:line where possible
(`src/mgf/common/process/_run.py:202`). The codebase has
file:line stability as a contract — the maintainer-side
agent (and the human reviewers) can navigate to the cited
line. Vague references ("the run() function") force a search.

## When in doubt

- **Search before filing.** Existing FEEDBACK entries may
  cover your concern. `grep "<keyword>" FEEDBACK.md`.
- **Read the rule before citing.** Paraphrasing is brittle.
- **Stay machine-friendly.** Tables, structured templates,
  paths-as-anchors. Avoid prose-only recommendations.
- **Honour scope.** `mgf-fed standards SCOPE`.
