Cookbook Projects

A self-contained, platform-agnostic project definition format. Define what your app is — generation tools produce native code for any platform.

What is a Cookbook Project?

A cookbook project is a directory containing a cookbook-project.json manifest and supporting files — recipes, resources, and context. Think of it like an Xcode project, but at a higher abstraction level.

The manifest is the single source of truth. It defines the complete project tree — components, dependencies, resources, and context. Files in the directory that aren't referenced in the manifest are ignored.

Recipes start from the cookbook when available — they're forked, customized for the project, and can be contributed back upstream. Resources like localization strings, icons, and app configs are defined in platform-neutral JSON that generates to native formats per platform.

Multi-Platform, Not Cross-Platform

The project format is platform-agnostic. The same project definition generates to Swift/SwiftUI on Apple, Kotlin on Android, C#/WinUI on Windows — native, best-of-class code for each platform. Not cross-platform lowest-common-denominator.

With agentic programming, the right constraints and instructions (recipes) can produce native code for any platform. The project defines what to build. The platform is a parameter at generation time.

Project Structure

my-app-cookbook-project/
├── cookbook-project.json        ← the manifest
├── app/
│   ├── app.md                  ← recipe: app entry point
│   └── document-window/
│       ├── document-window.md  ← recipe: main window
│       ├── toolbar/
│       │   └── toolbar.md
│       └── editor/
│           └── editor.md
├── resources/
│   ├── app-config.json         ← generates to Info.plist, AndroidManifest, etc.
│   ├── app-icon.json           ← generates to .xcassets, drawable/, etc.
│   └── strings.json            ← generates to .strings, .xml, .resx, etc.
└── context/
    ├── decisions/              ← architectural decisions
    ├── research/               ← design research and evaluations
    └── notes/                  ← project notes

The Manifest

The cookbook-project.json file defines the entire project as a hierarchical tree of components:

{
  "type": "cookbook-project",
  "schema_version": "1.0.0",
  "name": "My Document Editor",
  "platforms": ["ios", "macos", "windows"],
  "cookbook": {
    "repo": "https://github.com/agentic-cookbook/cookbook",
    "version": "1.0.0"
  },
  "components": {
    "app": {
      "recipe": "app/app.md",
      "components": {
        "document-window": {
          "recipe": "app/document-window/document-window.md",
          "source": {
            "domain": "agentic-cookbook://recipes/ui/windows/document-window",
            "version": "1.0.0"
          },
          "components": {
            "toolbar": { "recipe": "app/document-window/toolbar/toolbar.md" },
            "editor": {
              "recipe": "app/document-window/editor/editor.md",
              "depends-on": ["app.document-window.toolbar"]
            }
          }
        }
      }
    }
  }
}

Key Concepts

Components

Named nodes in a tree. Each has a recipe (markdown spec), optional resources, and nested children. A component without a recipe is a grouping node.

Resources

Platform-agnostic definitions — localization, icons, app config, sounds, data. JSON files that generate to native formats per platform.

Context

Research, decisions, and notes. Not generated to code, but provides background for the LLM.

Provenance

Recipes forked from the cookbook track their source domain and version. Tools can diff against the original for contribution back.

Lifecycle

Create — Describe what you want to build. A tool scaffolds the project, pulling starter recipes from the cookbook.
Refine — Iterate on the definition. Add components, customize recipes, add resources and context.
Generate — Tools read the manifest and produce native code for target platforms.
Iterate — Run, test, refine the generated code. Port improvements back to the project recipes.
Contribute — Push improved recipes back to the cookbook via the existing contribution workflow.

Resource Types

Type	Description	Generates to
localization	Translated UI strings	.strings (Apple), .xml (Android), .resx (Windows)
asset-catalog	Images, icons, color sets	.xcassets (Apple), drawable/ (Android)
app-manifest	App identity & capabilities	Info.plist, AndroidManifest.xml, Package.appxmanifest
sound	Audio assets	Platform-native audio formats
data	Static data files	Bundled as-is or transformed per platform

Full spec → appendix/decisions/cookbook-project-format JSON Schema → cookbook-project.schema.json Example project → my-document-editor-cookbook-project