RFC: Recipe organization for a multi-language future

[webchick]

RFC: Recipe organization for a multi-language future

Status: Draft — looking for input before doing anything.

The problem

Current structure groups by topic (agents/, foundations/, mcp/, deep_research/) with language as a suffix on each recipe name. That worked when everything was Python.

It starts to break down as we add TypeScript (Vercel AI SDK is already in flight) and as we want core concepts like Hello World and human-in-the-loop available in every Temporal SDK:

• A TS port of human_in_the_loop_python would sit next to it with no signal they're related
• "What's available for Go?" requires scanning every directory
• No obvious place for shared docs about the concept itself
• Categorization already strains — agentic_loop_tool_call_claude_python is arguably both "agents" and "foundations"

Proposal: concept-first, language-second

recipes/
  hello-world/
    README.md            # explains the concept, lists impls
    python-openai/
    python-litellm/
    typescript-vercel/
  human-in-the-loop/
    README.md
    python/
  agentic-loop-tool-calling/
    README.md
    python-claude/
    python-openai/

Each top folder is a concept. Sub-folders are implementations. Topic categorization (agents/foundations/etc.) moves to tags in the concept README so a recipe can be in multiple categories.

Missing language implementations become a visible "contributions welcome" signal instead of an invisible gap.

Alternatives I considered and rejected

• Language-first (python/, typescript/, etc.) — makes cross-language consistency worse, not better
• Keep current + add tagging — papers over the problem; we'd probably end up doing the full reorg in a year anyway

Open questions I need help with

1. Docs team: (@lennessyy ) does docs.temporal.io/ai-cookbook support a concept-with-multiple-impls page structure? How disruptive would URL changes be? 👀
2. In-flight PRs: we have 33 open. Land them first, then reorg? Or reorg and rebase ourselves?
3. Naming the concepts — bikeshedding welcome once we agree on direction.

What I want from this thread

Not a decision today. I want to know:

• Does the framing of the problem resonate, or am I missing something?
• Docs team: is this feasible on your side?
• Anyone who's done multi-language sample repos elsewhere — what worked, what didn't?

If there's rough agreement on direction, I'll follow up with a concrete migration plan. If there's a strong reason this is wrong, now is by far the cheapest time to tell me. :)

[webchick]

Actually, there's another angle on this:

Use case * SDK Language * AI Ecosystem Integration

😱

[webchick]

On the plus side, Lenny says that it's about a half hour of work to get the docs updated once we make up our mind here. :)