Ingredient / Recipe / Cookbook Artifact Hierarchy

Problem

The cookbook's artifact abstraction had two issues:

1. "Recipe" conflated atoms and compositions. All 27 recipes were atomic component specs (empty-state, file-tree-browser, settings-window). There was no way to define how multiple specs wire together into a coherent feature — that composition only existed implicitly in the cookbook-project manifest's component tree.

2. "Cookbook-project" was overloaded. The word "project" collides with IDE projects, GitHub projects, and general usage. Every conversation about cookbook projects required disambiguation.

Decision

Introduce a three-tier hierarchy:

Key design choices

Ingredients declare configurable options. Each ingredient has a ## Configuration section listing the knobs it exposes (option name, type, default, description). Recipes specify configuration values when including an ingredient.

Recipes are integration-focused. A recipe does not repeat per-component detail (appearance, states, accessibility) — that lives in the ingredients. A recipe answers: how do these ingredients wire together? What state flows between them? What breaks at the integration boundaries?

Cookbooks use "structure" not "components." The manifest's top-level field is "structure" (a single object representing the thing being built), with "structural-elements" for children. Each node references a "spec" file (not "recipe"), since it could be based on either an ingredient or a recipe.

Principles and guidelines are unchanged. They sit alongside the ingredient/recipe/cookbook hierarchy as reference material, not part of the cooking metaphor.

Alternatives Considered

Minimal type extension

Add ingredient and concoction as types but keep one shared markdown format for both ingredients and recipes, differentiating only by the type field.

Rejected because: ingredients and recipes answer fundamentally different questions. A shared format would have many N/A sections in recipes and missing integration sections in ingredients. Purpose-built formats are clearer for both LLM and human consumers.

Single format with conditional sections

One markdown format with conditional compliance checks: "applies when type is ingredient," "applies when type is recipe."

Rejected because: conditional compliance is harder to reason about and implement in tooling. Separate formats with separate compliance files are simpler.

Schema Changes

The cookbook-project.schema.json is superseded by cookbook.schema.json. Key renames:

Scope

This decision defines the formats and schema only. Reclassification of the existing 27 recipes into ingredients and recipes is a separate future effort.

Sibling Project Impact

agenticcookbookweb

Will need updates to recognize the three artifact tiers:

• New route structure for /ingredients/
• Updated navigation to show ingredients vs recipes
• Cookbook rendering (if the web app shows project definitions)

dev-team

Skills referencing "recipe" need audit:

• /plan-cookbook-recipe — may need renaming or handling both types
• /dev-team lint — must recognize type: ingredient
• /validate-cookbook — must validate ingredients/ directory and new frontmatter fields
• Artifact skills (/lint-artifact, /approve-artifact, /create-artifact) — must handle type: ingredient
• Agent descriptions that say "recipe" may need updating

These are documented here as future work items, not part of this decision's implementation scope.

Change History