alexsoyes · Oct 12, 2026 · Jul 26, 2026 · Aug 7, 2026 · Aug 7, 2026 · Aug 7, 2026
@@ -236,7 +236,7 @@ Start with a functional need or User Story, then track it as an issue or ticket
 before planning. Shipping follows the project's own delivery process. Capture a
 learning only when it is durable enough to improve the next feature.
 
-> 🍳 **More flows** → bundled recipes: [start a project](plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md), [ship a feature](plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md), and more.
+> 🍳 **More flows** → bundled recipes: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), and [installing AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md).
 
 ## 🧩 Plugins
 
@@ -338,7 +338,7 @@ Full catalog → [`CATALOG.md`](docs/CATALOG.md).
 
 | | |
 | --- | --- |
-| 🍳 **Recipes** | Bundled how-to sheets: [start a project](plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md), [ship a feature](plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md), [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
+| 🍳 **Recipes** | Bundled how-to sheets: [MCP installations](plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md), [token optimization](plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md), [install AIDDy](plugins/aidd-context/skills/12-cook/assets/recipes/install-aiddy-in-codex.md). Project recipes created by cook live in `aidd_docs/recipes/`. |
 | 🏛️ **[Architecture](docs/ARCHITECTURE.md)** | How the framework composes: plugins, skills, hooks, agents. |
 | 🧩 **[Create a plugin](docs/CREATE_PLUGIN.md)** | Build and publish your own. |
 | 🛒 **[Marketplace](docs/MARKETPLACE.md)** | Install scopes, versioning, LLM tiers. |

@@ -32,7 +32,7 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex
 | `09-mermaid`           | Generate Mermaid diagrams via a plan-validate workflow                        | `01-mermaid`                                                                                             |
 | `10-learn`             | Capture learnings, conventions, and decisions into memory, decisions, rules   | `01-gather`, `02-assess`, `03-write`, `04-sync`                                                          |
 | `11-explore`           | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill`                                                                                  |
-| `12-cook`              | Manage project and bundled recipes: list, create/update, research, or apply one | `01-list`, `02-upsert`, `03-research`, `04-apply`                                                        |
+| `12-cook`              | Manage and validate technical project or bundled recipes                       | `01-list`, `02-upsert`, `03-research`, `04-apply`, `05-validate`                                         |
 
 ## 💻 aidd-dev
 

@@ -53,6 +53,13 @@ pre-commit:
             exit 1
           fi
         done
+    recipe-validity:
+      run: |
+        if ! command -v node >/dev/null 2>&1; then
+          echo "❌ node not available; cannot validate recipes"
+          exit 1
+        fi
+        node plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs --all
     check-skill-argument-hints:
       glob: "plugins/*/skills/**"
       run: |

@@ -207,11 +207,13 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 | `actions` | [02-upsert.md](skills/12-cook/actions/02-upsert.md) | - |
 | `actions` | [03-research.md](skills/12-cook/actions/03-research.md) | - |
 | `actions` | [04-apply.md](skills/12-cook/actions/04-apply.md) | - |
+| `actions` | [05-validate.md](skills/12-cook/actions/05-validate.md) | - |
 | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - |
 | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - |
 | `assets` | [research-goal-checklist.md](skills/12-cook/assets/research-goal-checklist.md) | - |
+| `assets` | [validation-report-template.md](skills/12-cook/assets/validation-report-template.md) | - |
 | `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - |
 | `references` | [recipe-locations.md](skills/12-cook/references/recipe-locations.md) | - |
 | `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - |
-| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage project recipes/how-to sheets by listing, creating, updating, researching, or applying a recipe. Use for recipe, cook, /cook, list, new, update, research, apply.` |
+| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.` |
 
@@ -21,7 +21,7 @@ Covers project bootstrap, the project memory bank, generation of context artifac
 | [1.4]      | [mermaid](skills/09-mermaid/SKILL.md)                 | Generate high-quality Mermaid diagrams from markdown content using a structured plan-validate workflow.                                                         |
 | [1.5]      | [learn](skills/10-learn/SKILL.md)                     | Capture durable learnings from the conversation or git history, score each, and route the worthwhile ones to memory, a decision record, a rule, or a new skill. |
 | [1.6]      | [explore](skills/11-explore/SKILL.md)                 | Survey the project across three axes (tooling, context, codebase), then drill into one axis and point to the best-matching item for a goal.                      |
-| [1.7]      | [cook](skills/12-cook/SKILL.md)                       | Maintain project recipes in `aidd_docs/recipes/` and bundled recipes shipped with the skill: list, research, create/update, or apply one.                    |
+| [1.7]      | [cook](skills/12-cook/SKILL.md)                       | Maintain project and bundled recipes: list, research, create/update, apply, or validate one or all.                                                        |
 
 ## Onboarding
 

@@ -1,31 +1,39 @@
 ---
 name: 12-cook
-description: Manage project recipes/how-to sheets by listing, creating, updating, researching, or applying a recipe. Use for recipe, cook, /cook, list, new, update, research, apply.
+description: Manage project recipes/how-to sheets by listing, creating, updating, researching, applying, or validating a recipe. Use for recipe, cook, /cook, list, new, update, research, apply, validate.
 argument-hint: recipe
 ---
 
 # Cook
 
-Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bundled recipes ship inside this skill under `assets/recipes/`.
+```mermaid
+flowchart LR
+    unnamed --> list
+    named-new --> research
+    named-update --> research
+    named-research --> research
+    named-apply --> apply
+    named-validate --> validate
+    list -->|list only| done([done])
+    list -->|create or update| research
+    list -->|select to apply| apply
+    research -->|standalone research| done
+    research -->|create, update, or selected insights| upsert
+    upsert --> validate
+    validate -->|standalone, pass or findings| done
+    validate -->|upsert, pass| done
+    validate -->|upsert, findings: repair| upsert
+    apply --> done
+```
 
 ## Actions
 
-| #   | Action     | Role                                                         | Input                 |
-| --- | ---------- | ----------------------------------------------------------- | --------------------- |
-| 01  | `list`     | List every recipe as a table                                | none                  |
-| 02  | `upsert`   | Create or update one recipe from the template               | recipe topic + fields |
-| 03  | `research` | Survey modern alternatives, gaps, and counter-intuitive wins | recipe or topic      |
-| 04  | `apply`    | Execute a recipe on the project as a confirmed todo list    | recipe                |
+Run the flow above. Read only the next action file.
 
-Run `list` to survey project and bundled recipes, `research` to gather insights, `upsert` to author one, `apply` to run an existing one against the project. Always run `research` before authoring or substantially updating a recipe — never draft from memory alone. Run `list` first when the user names no recipe.
-Before running an action, read its file in `actions/`, not only the table or assets.
-
-## References
-
-- `references/recipe-locations.md`: where project and bundled recipes live, how resolution works, and when writes target each home.
-- `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it.
-
-## Assets
-
-- `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses.
-- `assets/recipes/`: bundled recipes shipped with this skill.
+| Action | Does |
+| --- | --- |
+| list | list project and bundled recipes |
+| research | research one recipe or topic |
+| upsert | create or update one recipe |
+| apply | apply one existing recipe |
+| validate | validate one or all recipes |
@@ -4,27 +4,31 @@ Create or update one project recipe at `aidd_docs/recipes/<slug>.md`, scaffolded
 
 ## Input
 
-The recipe topic. Ask for any missing field (description, steps, verify, related) before writing.
+The recipe topic and any verified results from `research`.
 
 ## Output
 
 The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
 
 ## Process
 
-1. **Research.** For a new recipe or any substantial update, run `research` (03) on the topic and draft only from its verified results, never from memory.
+1. **Research.** For a new recipe or any substantial update, draft only from verified `research` (03) results, running it on the topic when those results are not already available, never drafting from memory.
 2. **Slug.** Derive a kebab-case `<slug>` from the topic.
 3. **Resolve.** Resolve existing recipes with [recipe-locations.md](../references/recipe-locations.md).
    - The project recipe exists: update `aidd_docs/recipes/<slug>.md` in place.
    - Only a bundled recipe exists: ask whether to copy it into `aidd_docs/recipes/<slug>.md` or edit the bundled one. Edit a bundled recipe only when the user asks for that framework-source change.
-4. **Dedup.** For a new recipe, run `list` and rate each near match in an overlap table `| Existing recipe | Source | Shared scope | Overlap |`, where `Overlap` is none, partial, or high.
+4. **Ask.** Ask only for a missing decision that changes the recipe's outcome or scope.
+5. **Dedup.** For a new recipe, run `list` and rate each near match in an overlap table `| Existing recipe | Source | Shared scope | Overlap |`, where `Overlap` is none, partial, or high.
    - On any `high`, recommend updating that recipe instead and ask update-or-create before scaffolding.
-5. **Scaffold.** Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed, applying [recipe-contract.md](../references/recipe-contract.md) to every section.
-6. **Fill.** Fill every placeholder. Never maintain a separate recipe index; `list` reads the files directly.
+6. **Scaffold.** Scaffold from [recipe-template.md](../assets/recipe-template.md) when needed, applying [recipe-contract.md](../references/recipe-contract.md) to every section while preserving verified commands, examples, limits, screenshots, and evidence and deleting narrative repetition.
+7. **Fill.** Fill every placeholder. Never maintain a separate recipe index; `list` reads the files directly.
+8. **Validate.** Run `validate` (05) after the write.
+   - On findings, return to Scaffold and Fill to repair the recipe, then rerun both checks until they pass; reuse verified research rather than restarting it for repairs.
 
 ## Test
 
 - A new or substantially-updated recipe is drafted from `research` results, not from memory.
-- `aidd_docs/recipes/<slug>.md` exists and follows the recipe contract: opens with a one-sentence description (no Goal label, no table), each step a `#### N)` emoji heading with a real example, no `<...>` placeholder left.
+- `aidd_docs/recipes/<slug>.md` exists and passes the recipe contract.
+- `validate` passes after the write; no validation finding is silently waived.
 - A bundled recipe is never overwritten unless the user explicitly asks to change a bundled/framework recipe.
 - A new recipe that highly overlaps an existing project or bundled recipe triggers an update-or-create prompt before scaffolding.
@@ -19,14 +19,15 @@ Every presented item is confirmed to exist, with its latest state and official l
 ## Process
 
 1. **Refine.** Fill [research-goal-checklist.md](../assets/research-goal-checklist.md) with the user until the target is precise: outcome, level, scope, grouping. Resolve and read the recipe with [recipe-locations.md](../references/recipe-locations.md) when it exists. Run `list` when it is unnamed.
-2. **Fan out.** Spawn one agent per angle in [research-playbook.md](../references/research-playbook.md) via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources.
+2. **Scout.** Cover every angle in [research-playbook.md](../references/research-playbook.md). The caller or orchestrator may isolate or parallelize independent angles; this action never requires a particular delegation mechanism. Return candidates with sources.
 3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear [research-checklist.md](../assets/research-checklist.md): gaps filled, unknowns surfaced, claims corroborated.
-4. **Verify.** Spawn one agent per surviving candidate via the `Task` tool to confirm it exists, capture its official link, and record its latest state (version or date). Drop any candidate that cannot be confirmed against an official source.
+4. **Verify.** Apply the playbook's candidate checks. Drop anything that cannot be confirmed against an official source.
 5. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, each item carrying its official link, then state a recommendation and why.
 6. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe.
 
 ## Test
 
 - The output has an alternatives table with pros and cons, a coverage-gaps list, and a counter-intuitive wins list, plus an explicit recommendation, and nothing is written to disk.
 - Every presented item carries an official link and was confirmed to exist; unverifiable candidates are dropped.
+- Every candidate clears the playbook's evidence and transferability criteria.
 - The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`.
@@ -0,0 +1,27 @@
+# 05 - Validate recipes
+
+## Input
+
+The recipe name, title, path, or `all`.
+
+## Output
+
+A report filled from [validation-report-template.md](../assets/validation-report-template.md).
+
+Validation is read-only. Never repair, reformat, or rewrite a recipe during this action.
+
+## Process
+
+1. **Resolve.** Resolve one recipe with [recipe-locations.md](../references/recipe-locations.md), or keep `all` as the full project-plus-bundled scope.
+2. **Check structure.** Resolve `../scripts/validate-recipe.mjs` from this loaded action file's directory and invoke `node <resolved-script-path> <resolved-recipe-path>` or `node <resolved-script-path> --all` from the project root, preserving its exit code and findings.
+3. **Check semantics.** Apply the Writing, Steps, and Evidence rules from [recipe-contract.md](../references/recipe-contract.md); record one line-specific finding per violated rule. For non-JSON snippets, use available native YAML, TOML, and shell parsers and record which languages could not be checked mechanically.
+4. **Report.** Fill the report template with merged deterministic and semantic findings, or the success summary.
+   - An unavailable optional parser is disclosed but does not fail an otherwise valid recipe.
+   - Do not suppress a finding because it requires editorial judgment.
+
+## Test
+
+- One valid recipe and `all` return PASS without changing tracked files.
+- A structural failure returns the validator table with file, line, rule, fix, and a non-zero exit code.
+- A semantic failure appears in the same table even when the deterministic script passes.
+- JSON is parsed mechanically; YAML, TOML, and shell use available tools, and unavailable parsers appear in the success summary or a relevant failure.
@@ -1,50 +1,19 @@
-# <Recipe title>
+<!-- Fill every placeholder, repeat the step scaffold as needed, and remove all scaffold comments from the finished recipe. Keep the H1 title, plain description sentence, then the steps in this order. -->
+# <!-- Recipe title -->
 
-<One sentence describing what this recipe gets the reader.>
+<!-- Write one plain sentence naming the observable outcome. -->
 
-## Why
+<!-- Add an optional table of contents between the description and steps only when the finished recipe has at least 10 steps; omit it from shorter recipes. -->
 
-<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.>
+## Steps to <!-- outcome -->
 
-## Steps to <the outcome the reader achieves>
+<!-- Name this section for the outcome, never just Steps. Use ### N) <emoji> Title for direct steps, or #### N) <emoji> Title under a ### category. Optional difficulty categories are ### 🟢 Beginner, ### 🟡 Intermediate, and ### 🔴 Expert. Number steps continuously across categories. -->
+### 1) <!-- emoji + action title -->
 
-### 🟢 Beginner
-
-#### 1) <emoji> <First step title>
-
-<One benefit-focused line of what and why, in prose.>
-
-1. <where it is, then install it from its URL>
-2. <how to invoke it — its real command or slash>
-
-```bash
-$ <command the reader runs>
-<the useful output it prints, trimmed to what matters>
-```
-
-### 🟡 Intermediate
-
-#### 2) <emoji> <Next step title>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-2. <action>
-
-```<lang>
-<a config or snippet the reader can copy>
-```
-
-### 🔴 Expert
-
-#### 3) <emoji> <Last step title — until the goal is reached>
-
-<Benefit-focused what and why, in prose.>
-
-1. <action>
-
-![<what this screenshot or video shows>](<path-or-url>)
+<!-- Start with one sentence naming the benefit or risk, and state where and when this applies. -->
+<!-- Add only the actions needed to perform and verify the technique. Number them when there is more than one. -->
+<!-- Include one typed, copyable command/config/output, concrete table, or operational image from a real source. -->
 
 ## Verify
 
-- <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.>
+<!-- Add an observable command output, UI state, or file check; omit only when no useful check exists. -->