🏗️ feat(aidd-context): cook research + apply actions

README.md

@@ -208,7 +208,7 @@ flowchart TD
     class PR done;
 ```
 
-> 🍳 **More flows** → the [recipes](recipes/): [start a project](recipes/start-a-project.md), [ship a feature](recipes/ship-a-feature.md), and more.
+> 🍳 **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.
 
 ## 🧩 Plugins
 
@@ -294,7 +294,7 @@ Full catalog → [`CATALOG.md`](docs/CATALOG.md).
 
 | | |
 | --- | --- |
-| 🍳 **[Recipes](recipes/)** | How-to sheets: [start a project](recipes/start-a-project.md), [ship a feature](recipes/ship-a-feature.md), [MCP installations](recipes/mcp-installation.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/`. |
 | 🏛️ **[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. |

aidd_docs/CONTRIBUTING.md

@@ -40,6 +40,10 @@ When tools differ in syntax (frontmatter, slash command name, references), follo
 - Keep skills router-pure: SKILL.md holds no business logic; everything lives inside actions.
 - Stay within 5 to 10 percent deviation from a template structure. Beyond that, update the template first, then derive the new content from it.
 
+## Recipes
+
+Project recipes live under `aidd_docs/recipes/`. Bundled framework recipes live in the cook skill and should only be changed when contributing to the framework itself.
+
 ## Conventions
 
 - Skill names: `<plugin>:<NN>-<slug>`. Slug is kebab-case verb for activity domains, singular noun for tool domains.

aidd_docs/README.md

@@ -24,6 +24,7 @@ A plugin marketplace of skills, agents, rules, templates, and a memory system. Y
 | Block     | Location                                          | What it does                                                                          |
 | --------- | ------------------------------------------------- | ------------------------------------------------------------------------------------- |
 | Memory    | `aidd_docs/memory/`                               | Project context the AI reads on every conversation                                    |
+| Recipes   | `aidd_docs/recipes/`                              | Project-specific how-to sheets created by the cook skill                              |
 | Skills    | plugin `skills/` folders                          | Router-based workflows triggered by user phrases or slashes                           |
 | Commands  | tool-specific commands dir (when supported)       | Plain slash commands (no router); used for shortcuts and simple flows. None currently shipped by AIDD; reserved for future plugins or your own additions |
 | Agents    | plugin `agents/` folders                          | Specialized AI personas for focused tasks                                             |
@@ -70,6 +71,7 @@ my-project/
 │   ├── internal/
 │   │   └── decisions/           # Decision records written by aidd-context:10-learn
 │   ├── tasks/                   # Specs, plans, run summaries
+│   ├── recipes/                 # Project-specific cook recipes
 │   ├── ADR.md                   # Architecture decision log (aidd-context:10-learn)
 │   ├── README.md                # This file
 │   ├── GUIDELINES.md            # Developer operating guidelines

aidd_docs/recipes/.gitkeep

@@ -0,0 +1 @@
+

docs/CATALOG.md

@@ -30,7 +30,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 the project's recipes/ how-to sheets: list, create, or update one      | `01-list`, `02-upsert`                                                                                   |
+| `12-cook`              | Manage project and bundled recipes: list, create/update, research, or apply one | `01-list`, `02-upsert`, `03-research`, `04-apply`                                                        |
 
 ## 💻 aidd-dev
 

plugins/aidd-context/CATALOG.md

@@ -189,6 +189,13 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 |-------|------|---|
 | `actions` | [01-list.md](skills/12-cook/actions/01-list.md) | - |
 | `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) | - |
 | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - |
-| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes and how-to sheets. List them as a table, or create and update one from the canonical template. Use when the user wants to list, create, update, or cook a recipe.` |
+| `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - |
+| `assets` | [research-goal-checklist.md](skills/12-cook/assets/research-goal-checklist.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.` |
 

plugins/aidd-context/README.md

@@ -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 the project's `recipes/` how-to sheets: list every recipe, or create and update one from the canonical recipe template.                              |
+| [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.                    |
 
 ## Onboarding
 

plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md

@@ -1,21 +1,22 @@
 # 02 - Scaffold docs
 
-Create the `aidd_docs/` structure: root docs and empty memory subdirectories.
+Create the `aidd_docs/` structure: root docs, empty memory subdirectories, and the project recipe directory.
 
 ## Input
 
 The project root.
 
 ## Output
 
-`aidd_docs/` with `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`, `memory/README.md`, and `memory/{internal,external}/.gitkeep`.
+`aidd_docs/` with `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`, `memory/README.md`, `memory/{internal,external}/.gitkeep`, and `recipes/.gitkeep`.
 
 ## Process
 
 1. **Docs.** Write each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md` from its `@../assets/` template if absent, else update in place preserving the user's edits.
 2. **Memory dirs.** Ensure `aidd_docs/memory/internal/` and `aidd_docs/memory/external/` exist, each with a `.gitkeep`.
-3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent; leave an existing one.
+3. **Recipe dir.** Ensure `aidd_docs/recipes/` exists with a `.gitkeep`; recipe files created by cook live there.
+4. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent; leave an existing one.
 
 ## Test
 
-- `aidd_docs/` holds the three docs, `memory/README.md`, and both memory subdirectories with their `.gitkeep`.
+- `aidd_docs/` holds the three docs, `memory/README.md`, both memory subdirectories with their `.gitkeep`, and `recipes/.gitkeep`.

plugins/aidd-context/skills/02-project-memory/assets/CONTRIBUTING.md

@@ -11,6 +11,10 @@ Add or edit a file under `aidd_docs/memory/`. See [`memory/README.md`](memory/RE
 - Use the generator skills (`aidd-context:04-skill-generate` through `08-hook-generate`, and `10-learn` for memory or rules). They scaffold the right shape and write to the right place for each tool you use.
 - Open a pull request for anything that changes how the AI behaves on this project. The team reviews it like any code change.
 
+## Adding recipes
+
+Create or edit project recipes under `aidd_docs/recipes/`. Use the cook skill when available so new recipes follow the shared contract and do not overwrite bundled framework recipes.
+
 ## House conventions
 
 - <A naming or placement rule specific to this repo>

plugins/aidd-context/skills/02-project-memory/assets/README.md

@@ -5,6 +5,7 @@ Structured context the AI assistant reads to work on this project, so it does no
 ## What lives here
 
 - `memory/`: the project memory bank loaded each session. See [`memory/README.md`](memory/README.md).
+- `recipes/`: project-specific how-to recipes created or updated by the cook skill.
 - `GUIDELINES.md`: how this team operates the AI on this project.
 - `CONTRIBUTING.md`: how to add or change project context.
 - `tasks/`: specs, plans, and run summaries, created as work happens.

plugins/aidd-context/skills/12-cook/SKILL.md

@@ -1,23 +1,31 @@
 ---
 name: 12-cook
-description: Manage the project's recipes and how-to sheets. List them as a table, or create and update one from the canonical template. Use when the user wants to list, create, update, or cook a recipe.
-argument-hint: list | upsert
+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.
+argument-hint: list | upsert | research | apply
 ---
 
 # Cook
 
-Maintains the project's `recipes/` how-to sheets, the short runbooks that live at the project root.
+Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bundled recipes ship inside this skill under `assets/recipes/`.
 
 ## 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 |
+| #   | 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 `list` to survey recipes, `upsert` to author one. Run `list` first when the user wants to update a recipe but hasn't named which.
+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. Its header comment carries the field rules.
+- `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses.
+- `assets/recipes/`: bundled recipes shipped with this skill.

plugins/aidd-context/skills/12-cook/actions/01-list.md

@@ -1,24 +1,33 @@
 # 01 - List recipes
 
-List every recipe under `recipes/` at the project root as a table, excluding `README.md`.
+List project recipes and bundled recipes as a table.
+
+```md
+@../references/recipe-locations.md
+```
 
 ## Output
 
 ```md
-| Recipe | Goal | Level |
-| --- | --- | --- |
-| [<title>](recipes/<file>) | <goal> | <level> |
+| # | Recipe | Source | Description |
+| ---: | --- | --- | --- |
+| <n> | [<title>](<path>) | project \| bundled | <description> |
 ```
 
-One row per `recipes/*.md`, sorted by file name. If `recipes/` is absent or empty: `No recipes yet.`
+One row per recipe file, sorted by source then file name, numbered from 1 after sorting. If both homes are absent or empty: `No recipes yet.`
 
 ## Process
 
-1. Read each `recipes/*.md` except `README.md`.
-2. Pull the H1 title, the `> **Goal:**` line, and the **Level** row.
-3. Render the table above.
+1. Read project recipes under `aidd_docs/recipes/*.md`, excluding `README.md`.
+2. Read bundled recipes under `@../assets/recipes/*.md`, excluding `README.md`.
+3. Pull the H1 title and the one-sentence description right below it.
+4. If a project recipe and bundled recipe share the same slug, mark the project row as active and the bundled row as shadowed.
+5. Assign contiguous numbers from 1 to N after sorting.
+6. Render the table above.
 
 ## Test
 
-- One row per recipe file, each with title, goal, and level.
-- Absent/empty `recipes/` → `No recipes yet`, no error.
+- One row per project and bundled recipe file, each with number, title, source, and description.
+- A project recipe with the same slug as a bundled recipe is marked active and overrides the bundled copy.
+- Numbers are contiguous, start at 1, and match the displayed sort order.
+- Absent/empty project and bundled homes → `No recipes yet`, no error.

plugins/aidd-context/skills/12-cook/actions/02-upsert.md

@@ -1,22 +1,35 @@
 # 02 - Upsert recipe
 
-Create or update one recipe at `recipes/<slug>.md`, scaffolded from `@../assets/recipe-template.md`.
+Create or update one project recipe at `aidd_docs/recipes/<slug>.md`, scaffolded from the recipe template and following the recipe contract:
+
+```md
+@../references/recipe-locations.md
+@../assets/recipe-template.md
+@../references/recipe-contract.md
+```
 
 ## Input
 
-The recipe topic. Ask for any missing field (level, time, prerequisites, steps, verify, related) before writing.
+The recipe topic. Ask for any missing field (description, steps, verify, related) before writing.
 
 ## Output
 
-The recipe file at `recipes/<slug>.md`, filled from the template, with its row added or refreshed in `recipes/README.md`.
+The recipe file at `aidd_docs/recipes/<slug>.md`, filled from the template.
 
 ## Process
 
-1. Derive a kebab-case `<slug>` from the topic → `recipes/<slug>.md`.
-2. If it exists, update in place; else scaffold from the template.
-3. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Goal | Level |`: link the title to `<slug>.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits.
+1. **Research first.** For a new recipe or any substantial update, run `research` (03) on the topic and draft only from its verified results — never from memory.
+2. Derive a kebab-case `<slug>` from the topic.
+3. Resolve existing recipes with `@../references/recipe-locations.md`.
+4. If the project recipe exists, update `aidd_docs/recipes/<slug>.md` in place.
+5. If only a bundled recipe exists, ask whether to copy/update it into `aidd_docs/recipes/<slug>.md` or edit the bundled framework recipe. Only edit bundled recipes when the user explicitly asks for that framework-source change.
+6. If the recipe is new, 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.
+7. Scaffold from the template when needed. Apply the contract to every section.
+8. Fill every placeholder. Do not maintain a separate recipe index; `list` reads the recipe files directly.
 
 ## Test
 
-- `recipes/<slug>.md` exists and matches the template, every section present, no `<...>` placeholder left.
-- `recipes/README.md` carries a row for `<slug>`: its title linked, plus the goal and level.
+- 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.
+- 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.