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

plugins/aidd-context/CATALOG.md

@@ -196,7 +196,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) | - |
+| `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - |
+| `assets` | [research-goal-checklist.md](skills/12-cook/assets/research-goal-checklist.md) | - |
 | `-` | [README.md](skills/12-cook/README.md) | - |
-| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe".` |
+| `references` | [recipe-contract.md](skills/12-cook/references/recipe-contract.md) | - |
+| `references` | [research-playbook.md](skills/12-cook/references/research-playbook.md) | - |
+| `-` | [SKILL.md](skills/12-cook/SKILL.md) | `Manage the project's recipes/ how-to sheets — list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe".` |
 

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

@@ -2,11 +2,13 @@
 
 # 12 - cook
 
-Maintain the project's `recipes/` how-to sheets: list them, or create and update one from the canonical template. The recipes are the short runbooks at the root of whatever project the skill runs in.
-
-| #   | Action                         | Purpose                                        |
-| --- | ------------------------------ | ---------------------------------------------- |
-| 01  | [list](actions/01-list.md)     | List every recipe as a table.                  |
-| 02  | [upsert](actions/02-upsert.md) | Create or update one recipe from the template. |
+Maintain the project's `recipes/` how-to sheets: list, create or update, research, or apply. The recipes are the short runbooks at the root of whatever project the skill runs in.
+
+| #   | Action                             | Purpose                                                    |
+| --- | ---------------------------------- | --------------------------------------------------------- |
+| 01  | [list](actions/01-list.md)         | List every recipe as a table.                             |
+| 02  | [upsert](actions/02-upsert.md)     | Create or update one recipe from the template.            |
+| 03  | [research](actions/03-research.md) | Survey alternatives, gaps, and counter-intuitive wins.    |
+| 04  | [apply](actions/04-apply.md)       | Execute a recipe on the project as a confirmed todo list. |
 
 See [`SKILL.md`](SKILL.md) for the router and [`assets/recipe-template.md`](assets/recipe-template.md) for the recipe shape.

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

@@ -1,6 +1,6 @@
 ---
 name: 12-cook
-description: Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe".
+description: Manage the project's recipes/ how-to sheets — list, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe".
 ---
 
 # Cook
@@ -9,13 +9,19 @@ Maintains the project's `recipes/` how-to sheets, the short runbooks that live a
 
 ## 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 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.
+
+## References
+
+- `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.

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

@@ -5,20 +5,20 @@ List every recipe under `recipes/` at the project root as a table, excluding `RE
 ## Output
 
 ```md
-| Recipe | Goal | Level |
-| --- | --- | --- |
-| [<title>](recipes/<file>) | <goal> | <level> |
+| Recipe | Description |
+| --- | --- |
+| [<title>](recipes/<file>) | <description> |
 ```
 
 One row per `recipes/*.md`, sorted by file name. If `recipes/` is 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.
+2. Pull the H1 title and the one-sentence description right below it.
 3. Render the table above.
 
 ## Test
 
-- One row per recipe file, each with title, goal, and level.
+- One row per recipe file, each with title and description.
 - Absent/empty `recipes/` → `No recipes yet`, no error.

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

@@ -1,17 +1,26 @@
 # 02 - Upsert recipe
 
-Create or update one recipe at `recipes/<slug>.md`, scaffolded from `@assets/recipe-template.md`.
+Create or update one recipe at `recipes/<slug>.md`, scaffolded from the recipe template and following the recipe contract:
+
+```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.
 
 ## 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 → `recipes/<slug>.md`.
+3. If `recipes/<slug>.md` is new, run `list` and rate each near match in an overlap table `| Existing recipe | 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.
+4. If it exists, update in place; else scaffold from the template. Apply the contract to every section.
+5. Fill every placeholder, then add or refresh the recipe's row in the `recipes/README.md` index. The index table is `| Recipe | Description |`: link the title to `<slug>.md` (relative) and copy the one-sentence description. Same columns `list` emits.
 
 ## Test
 
-- `recipes/<slug>.md` exists and matches the template, every section present, no `<...>` placeholder left.
+- A new or substantially-updated recipe is drafted from `research` results, not from memory.
+- `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 new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding.

plugins/aidd-context/skills/12-cook/actions/03-research.md

@@ -0,0 +1,47 @@
+# 03 - Research alternatives
+
+Refine the target recipe with a checklist, scout for the highest-value insights, verify each one exists, and propose them as sorted lists.
+
+## Input
+
+The recipe or topic to modernize. If a recipe, its `recipes/<slug>.md` holds the current approach and coverage.
+
+## Output
+
+Three parts, then a recommendation:
+
+1. An alternatives table `| Alternative | What it is | Pros | Cons | Official link |`, sorted by value.
+2. A coverage-gaps list: important sub-topics the recipe omits, each with why it matters.
+3. A counter-intuitive wins list: surprising tips, each with the result it produces.
+
+Every presented item is confirmed to exist, with its latest state and official link. Ephemeral: nothing is written under `recipes/`.
+
+## Process
+
+1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/<slug>.md` first when the recipe exists. Run `list` when it is unnamed.
+
+```md
+@assets/research-goal-checklist.md
+```
+
+2. **Fan out.** Spawn one agent per angle in the playbook 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.
+
+```md
+@references/research-playbook.md
+```
+
+3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear the research checklist: gaps filled, unknowns surfaced, claims corroborated.
+
+```md
+@assets/research-checklist.md
+```
+
+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.
+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.
+- The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`.

plugins/aidd-context/skills/12-cook/actions/04-apply.md

@@ -0,0 +1,24 @@
+# 04 - Apply recipe
+
+Analyse a chosen recipe, ask the user what to do, then run the agent-doable steps and report the rest.
+
+## Input
+
+The recipe to apply, named by slug or topic.
+
+## Output
+
+A short analysis of the recipe — what it achieves, and which steps the agent can run versus which are the human's — then, on the user's choice, the chosen steps carried out and a report of what is left for the human.
+
+## Process
+
+1. **Locate.** Resolve the recipe to `recipes/<slug>.md` and read it. Run `list` first when the recipe is unnamed.
+2. **Analyse.** Read each step and classify it: agent-doable (a file edit, a config change) or human-only (a TUI command, an install, anything needing the user's terminal or UI). Summarise what the recipe achieves and what is in scope for the agent.
+3. **Ask.** Show the analysis and ask the user what to do — run all agent-doable steps, a subset, or just report. Never mutate before this answer.
+4. **Execute.** For the chosen steps, work them as a tracked todo list, pausing for confirmation on any step that changes a file. Leave the human-only steps untouched.
+5. **Report.** Report what was done, list the human-only steps as instructions for the user, and run any `## Verify` checks.
+
+## Test
+
+- Applying a recipe first produces an analysis that marks each step agent-doable or human-only, then asks the user what to do before any change.
+- The chosen agent-doable steps run as a todo list; human-only steps are reported as instructions, never executed.

plugins/aidd-context/skills/12-cook/assets/recipe-template.md

@@ -1,29 +1,50 @@
-<!-- Recipe contract: file is recipes/<kebab-slug>.md · Level ∈ {Beginner, Intermediate, Advanced} · Time prefixed with ~ · one idea per sentence, prefer removing over adding. -->
-
 # <Recipe title>
 
-> **Goal:** <one line stating the outcome the reader achieves>
-
-|                   |                                          |
-| ----------------- | ---------------------------------------- |
-| **Level**         | <Beginner \| Intermediate \| Advanced>   |
-| **Time**          | ~<N> min                                 |
-| **Prerequisites** | <what the reader needs first, or "None"> |
+<One sentence describing what this recipe gets the reader.>
 
 ## Why
 
-<One short paragraph: the problem this recipe solves and when to reach for it.>
+<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.>
 
-## Steps
+## Steps to <the outcome the reader achieves>
 
-1. 📋 **<First step>** — <imperative instruction.>
-2. 🔧 **<Next step>** — <imperative instruction.>
-3. ✅ **<Last step>** — <until the goal is reached.>
+### 🟢 Beginner
 
-## Verify
+#### 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>
 
-- <An observable check that proves it worked: a command, a UI state, a file that now exists.>
+<Benefit-focused what and why, in prose.>
 
-## Related
+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>)
+
+## Verify
 
-- <Link to a sibling recipe, a skill, or a doc the reader needs next.>
+- <Optional. An observable check that proves it worked: a command, a UI state, a file that now exists.>

plugins/aidd-context/skills/12-cook/assets/research-checklist.md

@@ -0,0 +1,9 @@
+<!-- Tick before drafting in 03-research. A research pass is done only when all three clear. -->
+
+# Research checklist
+
+A pass is done only when all three clear. Never draft from memory alone.
+
+- [ ] **Fill gaps** — cover what the starting list missed.
+- [ ] **Surface unknowns** — search past what you already know; assume blind spots exist.
+- [ ] **Confirm claims** — corroborate every assertion you would write, or mark it unverified.

plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md

@@ -0,0 +1,12 @@
+<!-- Filled with the user before scouting in 03-research. Defines the target recipe. -->
+
+# Refine the goal
+
+Fill this with the user before scouting. A vague goal returns vague insights.
+
+- [ ] **Goal** — one sentence naming the precise outcome the recipe delivers.
+- [ ] **Audience and level** — who it is for, mapped to Beginner / Intermediate / Expert.
+- [ ] **Scope** — what is in and explicitly out, so the search stays bounded.
+- [ ] **Actionable insights** — every item is a concrete action with an observable result, never theory alone.
+- [ ] **Grouping** — insights are organized under the three recipe levels (Beginner / Intermediate / Expert).
+- [ ] **Counter-intuitive wins** — leave room for surprising tips that outperform the obvious default.

plugins/aidd-context/skills/12-cook/references/recipe-contract.md

@@ -0,0 +1,31 @@
+<!-- Cited by upsert. The rules every recipe file follows. -->
+
+# Recipe contract
+
+Rules for every `recipes/<kebab-slug>.md` the skill writes.
+
+## File
+
+- Path: `recipes/<kebab-slug>.md`.
+- The recipe opens with the H1 title, then one plain sentence of description — no "Goal:" label, no blockquote, no metadata table.
+- Sections: the description, `## Why`, then the steps. `## Verify` is optional — omit it when it adds little. End with an optional short conclusion. Never add a `## Related` section: links live inline where they are used.
+
+## Writing
+
+- One idea per sentence. Prefer removing over adding.
+- No filler line under a heading (no "Ranked by impact", "Start at the top", and the like).
+- `## Why`: short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.
+
+## Steps
+
+- The steps section heading is named after the goal: `## Steps to <outcome>`, never a bare `## Steps`.
+- One step = one action: never bundle several tools or commands under one heading; split them.
+- Each step is a `#### N) <emoji> Title` heading, then one benefit-focused line of what and why in prose. Number steps continuously.
+- Write the actions to take as a numbered list; write any description or indication as prose, never as a bullet.
+- For a tool: where it is, install it from its URL, then how to invoke it (its real command or slash invocation, e.g. `/caveman`).
+- Reuse the tool's canonical example captured verbatim from its site or README — never a paraphrase, and never on the strength of a summary that says one exists.
+- Every step carries one concrete example. Prefer an image — a screenshot or short video/GIF that matches the action — over text whenever one exists; for a tool, use its official screenshot. Otherwise: a command with its real output, a config in the file's real syntax (valid JSON for `settings.json`, valid YAML for frontmatter, …), or a snippet.
+- A step that prefers one option over another uses a comparison table, not prose.
+- For a structural or flow concept (a proxy, a pipeline, an architecture), add a small Mermaid diagram with concrete example values.
+- Level subheadings are optional. Group steps under `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert` only when the recipe spans difficulty levels and grouping helps the reader; a short or single-level recipe lists its steps directly. Include only the levels that have a step.
+- Link to a reference when applicable.