Skip to content

Tier 2 AI Content Pipeline — Round 3 Review

Overall: NOT SHIP

I only found two genuinely factual issues after checking the document against the current MAID codebase.

1. HIGH — Section 4.3 (GenericJSONAdapter) describes current behavior that does not exist

What’s wrong

The document says the GenericJSONAdapter “works today” and that, until Phase 0 lands, providers use that path by injecting schema text into prompts (tier2-ai-content-pipeline.md:249-252, 1261-1264, 1452-1490). That is not true in the current codebase.

There is no GenericJSONAdapter implementation in packages/maid-engine/src/maid_engine/ai/ (ripgrep finds no class or symbol by that name), and the current provider API still only exposes plain-text CompletionOptions / CompletionResult fields in packages/maid-engine/src/maid_engine/ai/providers/base.py:91-113. The current maid dev generate path just calls llm.complete(...) and prints raw text in packages/maid-engine/src/maid_engine/cli/app.py:1175-1224.

Fix

Reword these passages to make the adapter explicitly proposed, e.g. “the planned fallback adapter is GenericJSONAdapter” / “until Phase 0 lands, current MAID has no structured-output adapter; the future fallback path will inject schema text into prompts.”

2. MEDIUM — “maid ai” is still not marked as proposed throughout

What’s wrong

R2 improved the main command-group section, but there are still later sections that describe nonexistent commands/features in present tense without a local proposal marker:

  • tier2-ai-content-pipeline.md:3524-3542 introduces maid ai generate-world with no “proposed / not yet implemented” note.
  • tier2-ai-content-pipeline.md:4798-4807 says maid dev generate “is deprecated” and shows @dev_app.command("generate", deprecated=True), but the real code is not deprecated today in packages/maid-engine/src/maid_engine/cli/app.py:1175-1183.

So the “marked PROPOSED throughout” fix is still incomplete.

Fix

Add explicit local proposal markers to Sections 10 and 15 (and any similar late-document command references), and change the migration text to future tense: “would be deprecated” / “planned migration path.”

What I verified as fixed

  • YAML examples are component-centric; I did not find stray top-level dialogue, schedule, relationships, or attributes fields in this doc.
  • ExtendedRoomComponent examples now use the real nested structure under descriptions, matching maid_stdlib.components.extended_room.ExtendedRoomComponent / ExtendedDescriptions.
  • ChatJimmy is consistently described as text-only.
  • Mock-provider transcript is now clearly labeled proposed UX.
  • ItemComponent is correctly labeled as a common/non-exhaustive field list.
  • @ai.accept now includes the explicit export-to-canonical rule.
  • Area vs Zone terminology is explicitly clarified.