diff --git a/README.md b/README.md index 412dd03b..a185504b 100644 --- a/README.md +++ b/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. | diff --git a/aidd_docs/CONTRIBUTING.md b/aidd_docs/CONTRIBUTING.md index b0549f52..7145ed99 100644 --- a/aidd_docs/CONTRIBUTING.md +++ b/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: `:-`. Slug is kebab-case verb for activity domains, singular noun for tool domains. diff --git a/aidd_docs/README.md b/aidd_docs/README.md index d4de7c2a..aac1bf1e 100644 --- a/aidd_docs/README.md +++ b/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 diff --git a/aidd_docs/recipes/.gitkeep b/aidd_docs/recipes/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/aidd_docs/recipes/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 3788ca9b..1a046c9d 100644 --- a/docs/CATALOG.md +++ b/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 diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 1783a184..5ed76aa5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/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.` | diff --git a/plugins/aidd-context/README.md b/plugins/aidd-context/README.md index fab12ea3..4eb56548 100644 --- a/plugins/aidd-context/README.md +++ b/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 diff --git a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md index 3056898c..c573beb6 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md @@ -1,6 +1,6 @@ # 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 @@ -8,14 +8,15 @@ 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`. diff --git a/plugins/aidd-context/skills/02-project-memory/assets/CONTRIBUTING.md b/plugins/aidd-context/skills/02-project-memory/assets/CONTRIBUTING.md index 8e495f31..9c1848aa 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/CONTRIBUTING.md +++ b/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 - diff --git a/plugins/aidd-context/skills/02-project-memory/assets/README.md b/plugins/aidd-context/skills/02-project-memory/assets/README.md index 7f0199fb..fb43b82a 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/README.md +++ b/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. diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index f1a41387..eacd5eca 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/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. diff --git a/plugins/aidd-context/skills/12-cook/actions/01-list.md b/plugins/aidd-context/skills/12-cook/actions/01-list.md index 543e18e9..3ee76cd5 100644 --- a/plugins/aidd-context/skills/12-cook/actions/01-list.md +++ b/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 | -| --- | --- | --- | -| [](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. diff --git a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md index c7e681e5..8dbe2176 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/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. diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md new file mode 100644 index 00000000..3514b6e5 --- /dev/null +++ b/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, named by number from the latest `list`, slug, title, or topic. If a recipe exists, resolve it from project recipes first, then bundled recipes. + +## 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 to either recipe home. + +## Process + +1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Resolve and read the recipe with `@../references/recipe-locations.md` when it 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`. diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md new file mode 100644 index 00000000..212bacdf --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -0,0 +1,25 @@ +# 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 number from the latest `list`, slug, title, 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 with `@../references/recipe-locations.md` and read it. Run `list` first when the recipe is unnamed or when the user gives a number but no current numbered list is available. +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. +- A numeric choice maps to the matching row from the latest `list`; if no current list exists, `apply` reruns `list` and asks for the number again. +- The chosen agent-doable steps run as a todo list; human-only steps are reported as instructions, never executed. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md index 278237ca..95a189c4 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/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.> diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md new file mode 100644 index 00000000..698280dd --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md @@ -0,0 +1,60 @@ +# MCP installations + +Decide when to use an MCP server vs a CLI, and wire up the recommended ones. + +## Why + +**MCP servers** load their full tool schema into every turn, which bloats the context window. + +**CLI calls** cost a few tokens and return only what you ask for. + +**Reach for MCP only when no CLI covers the service.** + +**Audit what you install** before connecting any server. + +## Steps to choose and install the right integration + +#### 1) ๐Ÿ”Ž Check for a CLI first + +The CLI is usually cheaper because it does not inject a large tool schema into every turn. + +1. Look for an official CLI before adding an MCP server. +2. Install and authenticate the CLI when it covers the workflow. +3. Keep MCP for services with no useful CLI alternative. + +| Service | Official MCP | CLI alternative | Recommended | +| --- | --- | --- | --- | +| **GitHub** | [`api.githubcopilot.com/mcp/`](https://github.com/github/github-mcp-server) | [`gh`](https://cli.github.com/) | **CLI**: issues, PRs, releases, and API calls without the MCP schema cost | +| **Atlassian** (Jira / Confluence) | [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) for Jira | **CLI** for Jira, **MCP** for Confluence | +| **Playwright** | [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | [`npx playwright`](https://playwright.dev/docs/test-cli) | **CLI**: a real browser through `playwright open`, `codegen`, or `--headed` | +| **Figma** | [`mcp.figma.com/mcp`](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | none for design data | **MCP** | +| **Notion** | [`mcp.notion.com/mcp`](https://developers.notion.com/guides/mcp/get-started-with-mcp) | none official | **MCP** | + +#### 2) ๐Ÿ”Œ Add MCP only when it is the right integration + +An MCP config belongs in the assistant's MCP configuration file, and only for services where MCP is the best available interface. + +1. Read the provider docs and permission model. +2. Add the server to `.mcp.json`. +3. Restart the assistant so it picks up the new tools. + +```json +{ + "mcpServers": { + "figma": { "url": "https://mcp.figma.com/mcp" } + } +} +``` + +#### 3) โœ… Verify the integration + +Verification keeps a bad install out of later sessions. + +1. For MCP, confirm the tools appear in the assistant. +2. For a CLI, run a read-only identity command. + +```bash +$ gh auth status +github.com + โœ“ Logged in to github.com account octocat +``` diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md b/plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md new file mode 100644 index 00000000..de5a4f7b --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md @@ -0,0 +1,79 @@ +# Ship a feature end to end + +Take a feature from a rough idea to a reviewed, shipped pull request with the AIDD flow. + +## Why + +The common loop, at a glance โ€” the exact commands to run so you never wonder what comes next. + +> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. + +## Steps to ship a feature + +#### 1) ๐Ÿ’ก Clarify + +Brainstorm turns the rough idea into a precise request. + +1. Run `/aidd-refine:01-brainstorm`. + +```text +/aidd-refine:01-brainstorm +``` + +#### 2) ๐Ÿ“‹ Plan + +Planning drafts the phased technical plan before implementation starts. + +1. Run `/aidd-dev:01-plan`. + +```text +/aidd-dev:01-plan +``` + +#### 3) ๐Ÿ”ง Implement + +Implementation writes the code phase by phase. + +1. Run `/aidd-dev:02-implement`. + +```text +/aidd-dev:02-implement +``` + +#### 4) ๐Ÿ” Review + +Review checks the diff before it ships. + +1. Run `/aidd-dev:05-review`. + +```text +/aidd-dev:05-review +``` + +#### 5) ๐Ÿ“ฆ Commit + +Commit records one atomic conventional change. + +1. Run `/aidd-vcs:01-commit`. + +```text +/aidd-vcs:01-commit +``` + +#### 6) โœ… Pull request + +The pull-request step opens the PR. + +1. Run `/aidd-vcs:02-pull-request`. + +```text +/aidd-vcs:02-pull-request +``` + +> One command for the whole loop: `/aidd-dev:00-sdlc` runs plan โ†’ implement โ†’ review โ†’ ship. + +## Verify + +- A pull request is open on your branch, with the diff reviewed and tests passing. + +Start with [Start a project](start-a-project.md) before your first feature. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md b/plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md new file mode 100644 index 00000000..85fe9c4d --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md @@ -0,0 +1,67 @@ +# Start a project (greenfield) + +Take a greenfield idea to a set-up project with its AIDD context, ready for the first feature. + +## Why + +The greenfield sequence, at a glance โ€” from a raw idea to a project the AIDD flow can build on. + +> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. + +## Steps to start a project + +#### 1) ๐Ÿ’ก Brainstorm the idea + +Brainstorming sharpens the raw idea into a precise request. + +1. Run `/aidd-refine:01-brainstorm`. + +```text +/aidd-refine:01-brainstorm +``` + +#### 2) ๐Ÿ“„ Draft the PRD + +The PRD turns the idea into structured product requirements. + +1. Run `/aidd-pm:03-prd`. + +```text +/aidd-pm:03-prd +``` + +#### 3) ๐Ÿ—๏ธ Design the architecture + +Bootstrap validates a stack through Q&A and outputs an `INSTALL.md`. + +1. Run `/aidd-context:01-bootstrap`. + +```text +/aidd-context:01-bootstrap +``` + +#### 4) ๐Ÿง  Build project memory + +Project memory creates the memory bank and AI context files. + +1. Run `/aidd-context:02-project-memory`. + +```text +/aidd-context:02-project-memory +``` + +#### 5) ๐Ÿš€ Ship the first feature + +The feature recipe takes the project through the per-feature loop. + +1. Follow [Ship a feature](ship-a-feature.md). + +```text +/aidd-dev:00-sdlc +``` + +## Verify + +- `aidd_docs/memory/` holds the memory files, and an `INSTALL.md` describes the chosen stack. + +Use `/aidd-context:00-onboard` any time to see where the project sits. diff --git a/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md new file mode 100644 index 00000000..67c096fa --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md @@ -0,0 +1,277 @@ +# Token optimization for AI IDEs + +Cut token usage and cost in AI coding assistants without losing output quality. + +## Why optimize your tokens + +**Token usage** is the bill โ€” every turn re-sends your whole **context window** and you pay for it again. + +Most of it is **waste**: filler prose, noisy logs, stale context, bloated instruction files. + +Reach for this recipe when **cost** climbs faster than your output. + +## Steps to cut token usage + +### ๐ŸŸข Beginner + +#### 1) ๐Ÿ”Ž See what fills the window โ€” `/context` + +`/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. + +1. Run `/context` in Claude Code. +2. Find the heavy blocks: tool schemas, instruction files, long file reads. +3. Attack the biggest block first. + +```text +$ /context + MCP tool schemas โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 28% โ† biggest, cut first + file reads โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 19% + CLAUDE.md โ–ˆโ–ˆโ–ˆโ–ˆ 9% +(illustrative โ€” replace with a screenshot of your real /context) +``` + +#### 2) ๐Ÿ’ธ Read the bill โ€” `/cost` + +`/cost` tells you what a session actually costs and where the spend goes. + +1. Run `/cost` (alias `/usage`). +2. Read the breakdown by skill, subagent, and MCP server. +3. Re-run it after a change to confirm the spend really dropped. + +```text +$ /cost + Session: $0.42 ยท 1.2M tokens + By: subagents 38% ยท MCP 21% ยท main 41% +(illustrative โ€” replace with a screenshot of your real /cost) +``` + +#### 3) ๐Ÿ” Find your bad habits โ€” `/insights` + +`/insights` analyses how you prompt โ€” probably sub-optimal โ€” so you fix the pattern, not one prompt. What you repeat every session belongs in the knowledge base, and the counter-intuitive habits you never noticed get surfaced so you can drop them. + +1. Run `/insights`. +2. Move what you repeat into `CLAUDE.md` or a rule, and drop the habits it flags. + +```text +$ /insights + โ€ข You restate the test command in ~60% of sessions โ†’ put it in CLAUDE.md + โ€ข Long "summary" turns inflate output โ†’ ask for terse replies +(illustrative โ€” replace with a screenshot of your real /insights) +``` + +#### 4) ๐Ÿ“ˆ Track per-prompt with an analytics tool + +Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. + +1. Pick one: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) or [`ccusage`](https://www.npmjs.com/package/ccusage). +2. Run it โ€” `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` โ€” no setup, it parses `~/.claude`. + +![prompt-analytics dashboard โ€” cost by token type shows cache reads dominate the bill](https://raw.githubusercontent.com/romainfjgaspard/prompt-analytics-for-claude-code/main/docs/screenshots/dashboard-home.png) + +#### 5) โœ‚๏ธ Trim your instruction file + +Your instruction file ships every turn, so each cut line saves on every message. + +1. Open `CLAUDE.md` (or `.github/copilot-instructions.md`). +2. Cut it to essentials and add explicit conciseness rules. +3. Model it on a real concise instruction file: [AGENTS.md](../../../02-project-memory/assets/AGENTS.md). + +```md +# CLAUDE.md โ€” keep it terse (see AGENTS.md for the full example) +- Answer first. Lead with the result, then the reason. Drop pleasantries and hedging. +- No tool-call narration. No decorative tables or emoji unless they carry information. +- Keep verbatim: code, quoted errors, security warnings. Cut the rest. +``` + +#### 6) ๐Ÿงญ Plan before you edit โ€” plan mode + +Approving the wrong direction burns tokens on rework, so let Claude explore read-only and propose a plan first. + +1. Press `Shift+Tab` twice to enter plan mode (or start with `claude --permission-mode plan`). +2. Review the plan, then approve to switch to execution. + +```text +Shift+Tab Shift+Tab โ†’ โธ plan mode + Claude reads and proposes; no edits until you approve +``` + +See [permission modes](https://code.claude.com/docs/en/permission-modes). + +#### 7) โ™ป๏ธ Clear context between tasks โ€” `/clear` + +Stale early turns ride along and get re-billed every turn, so reset when the task changes. + +1. Finish a task, then run `/clear` to drop the history and reload only `CLAUDE.md` and memory. +2. Use `/compact` instead when you want to keep a summary of the same task. + +```text +$ /clear + history dropped โ†’ fresh window, CLAUDE.md + memory reloaded +``` + +See [reduce token usage](https://code.claude.com/docs/en/costs). + +#### 8) ๐Ÿ—œ๏ธ Compact deliberately + +Compacting on your terms keeps what matters instead of letting auto-compaction guess. + +1. Watch context use and act around 60โ€“70%. +2. Run `/compact` with focus instructions naming what to keep. + +```text +$ /compact keep the repro steps and the failing test; drop the file dumps +``` + +### ๐ŸŸก Intermediate + +#### 9) ๐Ÿ—ฃ๏ธ Make the agent talk less + +Output is repetition you pay to generate, so cap the chatter. caveman forces short, filler-free replies (reported ~65% output cut, code intact) and auto-detects 30+ agents. + +1. Built-in route: set `"outputStyle": "concise"` in `settings.json`. +2. Harder cut: install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill and invoke it like any skill โ€” `/caveman` (or `/caveman ultra`); stop with "normal mode". + +```text +/caveman + +before: The reason your React component is re-rendering is likely because you're creating a new object reference on each render cycle. When you pass an inline object as a prop, React's shallow comparison sees it as a different object every time, which triggers a re-render. I'd recommend using useMemo to memoize the object. + +after: New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`. +``` + +See [output styles](https://code.claude.com/docs/en/output-styles). + +#### 10) ๐Ÿงน Filter noisy command output + +Test, install, and build logs flood context with lines the model never needs. + +1. Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). +2. Prefix your command with it: `rtk cargo test`. + +```mermaid +flowchart LR + A["rtk cargo test"] --> R[RTK proxy] + R --> C["cargo test runs"] + C -->|"~25,000 tokens"| R + R -->|"filter ยท group ยท dedupe"| M["~2,500 tokens to model"] +``` + +Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). + +#### 11) ๐Ÿšซ Keep big paths out of context โ€” deny reads + +Vendor dirs, build output, and secrets get pulled into context by accident. Deny reads on them so they stay out โ€” they remain grep-able. + +1. In `settings.json`, add `Read(...)` deny rules for large or sensitive paths. +2. `.claudeignore` is not shipped โ€” deny rules are the official way. + +```json +{ + "permissions": { + "deny": ["Read(./vendor/**)", "Read(./dist/**)", "Read(./.env)"] + } +} +``` + +See [permissions](https://code.claude.com/docs/en/permissions). + +#### 12) ๐Ÿ”Œ Prefer CLI over MCP + +An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. Newer MCP tooling adds tool/context selection that loads only the tools you pick โ€” cheaper than before โ€” but a CLI is still leaner and faster. + +| | CLI (`gh`, `acli`, โ€ฆ) | MCP server | +| --- | --- | --- | +| Token cost | a few, only when called | a schema every turn; less with tool/context selection | +| Speed | fastest | slower | +| Use when | a CLI exists | no CLI, or you need typed/live tool calls | + +See [`mcp-installation.md`](mcp-installation.md). + +### ๐Ÿ”ด Expert + +#### 13) ๐Ÿ”ฌ Audit which skills and tools run โ€” `Ctrl+O` + +You optimise what you can see, so expand the transcript to watch what each turn actually invokes and pulls into context. + +1. Press `Ctrl+O` to toggle the transcript โ€” it shows detailed tool and skill usage and expands collapsed MCP calls. +2. Spot skills or tools that load on turns that don't need them, then scope or remove them. + +```text +Ctrl+O โ€” transcript expanded + โŽฟ Skill: token-optimization + โŽฟ Called slack 3 times โ†’ expanded: 3 tool calls +(illustrative โ€” replace with a screenshot of your real Ctrl+O transcript) +``` + +See the [keyboard shortcuts](https://code.claude.com/docs/en/interactive-mode). + +#### 14) ๐ŸŽฏ Route by difficulty + +The top model on routine work is wasted spend, so pin the model per skill or agent โ€” cheap for routine, top-tier for hard reasoning. + +1. Set `model` in a skill's or an agent's frontmatter (`haiku` / `sonnet` / `opus`, a full id, or `inherit`). +2. Give routine scouts a small model; reserve `opus` for the hard reasoning. + +```yaml +# .claude/agents/explore.md โ€” routine scouting on a cheap model +--- +name: explore +description: Read-only codebase scout +tools: Read, Grep, Glob +model: haiku +--- +``` + +A skill's `SKILL.md` takes the same `model:` field (e.g. `model: opus` for a heavy step). See [sub-agents](https://code.claude.com/docs/en/sub-agents) and [skills](https://code.claude.com/docs/en/skills). + +#### 15) ๐Ÿงซ Offload high-volume work to subagents + +Test runs, log parsing, and wide exploration flood the main window. A subagent does it in its own context and hands back only a summary, so the bloat never lands in your session. + +1. Define an agent in `.claude/agents/<name>.md` with only the tools it needs and a small `model`. +2. Let it run the noisy op and return a short result. + +```yaml +# .claude/agents/test-runner.md +--- +name: test-runner +description: Run the suite and return only the failures +tools: Bash, Read +model: haiku +--- +``` + +See [sub-agents](https://code.claude.com/docs/en/sub-agents). + +#### 16) ๐ŸงŠ Protect your cache hits + +Cached input bills far cheaper, and cache reads are most of your tokens (step 4) โ€” so don't throw the cache away mid-task. A model switch, an MCP connect or disconnect, or an effort change rebuilds it from scratch. + +1. Set the model and reasoning effort at the start of a task, not mid-work. +2. Switch model or toggle MCP servers only at task boundaries, where a cache rebuild is acceptable. + +```text +mid-task model switch โ†’ cache invalidated โ†’ full re-bill +same model to a boundary โ†’ cache reads stay cheap +``` + +See [prompt caching](https://code.claude.com/docs/en/prompt-caching). + +#### 17) โœ… Cap extended thinking + +Extended reasoning can silently add thousands of tokens on tasks that don't need it. + +1. In `settings.json`, set `MAX_THINKING_TOKENS` to `0` for routine work. +2. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). + +```json +{ + "env": { + "MAX_THINKING_TOKENS": "0" + } +} +``` + +## In short + +Measure first, then stack the cheap wins โ€” trimmed instructions, plan mode, a clean context, less chatter, filtered output โ€” before the advanced routing, subagents, and cache discipline. Most of the bill is cache and repetition; cut those and the cost follows. diff --git a/plugins/aidd-context/skills/12-cook/assets/research-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-checklist.md new file mode 100644 index 00000000..89a99785 --- /dev/null +++ b/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. diff --git a/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md new file mode 100644 index 00000000..3ad21d32 --- /dev/null +++ b/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. diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md new file mode 100644 index 00000000..f06f1bf0 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -0,0 +1,32 @@ +<!-- Cited by upsert. The rules every recipe file follows. --> + +# Recipe contract + +Rules for every recipe file the skill writes. + +## File + +- Project path: `aidd_docs/recipes/<kebab-slug>.md`. +- Bundled path, only for explicit framework-source edits: `plugins/aidd-context/skills/12-cook/assets/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. diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-locations.md b/plugins/aidd-context/skills/12-cook/references/recipe-locations.md new file mode 100644 index 00000000..c869312c --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/recipe-locations.md @@ -0,0 +1,27 @@ +<!-- Cited by list, upsert, research, and apply. Defines where recipes live and how name resolution works. --> + +# Recipe locations + +Recipes have two homes: + +- **Project recipes**: `aidd_docs/recipes/<slug>.md`. These belong to the current project and are the default write target for `upsert`. +- **Bundled recipes**: `assets/recipes/<slug>.md` inside this skill. These ship with AIDD and are read-only during normal project use. + +## Resolution + +When a user names a recipe, resolve in this order: + +1. Number from the latest `list` table in the current conversation. +2. Exact slug in `aidd_docs/recipes/`. +3. Exact slug in `assets/recipes/`. +4. Title or topic match across both homes, showing candidates when more than one match is plausible. + +Numbers are display shortcuts only. They are scoped to the latest rendered `list` table and must not be stored in recipe files. If the user gives a number and no current numbered list is available, rerun `list` and ask the user to pick a number from the new table. + +If a project recipe and a bundled recipe share a slug, the project recipe overrides the bundled one. List both homes, but mark the project copy as the active one. + +## Writes + +`upsert` writes to `aidd_docs/recipes/` by default. + +Only write a bundled recipe when the user explicitly asks to change a bundled/framework recipe while working in the AIDD framework source. In that case, write to `plugins/aidd-context/skills/12-cook/assets/recipes/<slug>.md`. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md new file mode 100644 index 00000000..40db46c7 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -0,0 +1,38 @@ +<!-- Read before spawning research agents in 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. --> + +# Research playbook + +Guidance for `03-research`: the angles to scout, the criteria each candidate must clear, and the verification each must pass. Define the target with `assets/research-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. + +## Angles to cover + +Spawn one agent per angle so coverage stays wide: + +- **Alternatives** โ€” competing tools, libraries, or methods that could replace the current approach. +- **New methods** โ€” techniques that emerged since the recipe was written. +- **Coverage gaps** โ€” important sub-topics the recipe omits entirely. A masterclass that forgets a core feature has a gap. +- **Counter-intuitive wins** โ€” surprising practices that beat the obvious default, with evidence of the result. +- **Deprecations** โ€” what the recipe still recommends that is now discouraged or dead. + +## Criteria for every candidate + +- **Freshness** โ€” prefer sources from the last 12 months. Record release or publish dates. Flag anything stale. +- **Community signal** โ€” weigh what practitioners actually say: GitHub activity, open issues, Reddit, Hacker News, discussions. Separate real adoption from hype. +- **Tips and gotchas** โ€” capture practical advice, common pitfalls, and migration notes worth keeping. +- **Credibility** โ€” corroborate across sources. Trust official docs over a single blog post. + +## Verify each candidate + +After curating, confirm every surviving candidate before presenting it. Spawn one agent per candidate to check: + +- **Exists** โ€” confirm it is real and current, not invented or abandoned. +- **Official link** โ€” capture the canonical source: official docs, repository, or release page. +- **Latest state** โ€” record the current version or release date. +- **Real example** โ€” prefer an image: grab the official screenshot or GIF that matches the action. Else a real output: copy it from the docs, or run the command and capture what it prints. For interactive output that cannot be scripted, mark it for the human to paste (ideally a screenshot). Never fabricate. +- Drop any candidate that cannot be confirmed against an official source. + +## Reporting + +- Return each candidate with its angle, level, value, and a source; verified ones carry an official link. +- Push for the most insights possible, then drop anything that neither beats nor extends the recipe. +- `03-research` sorts them into three buckets: alternatives (with pros/cons), coverage gaps, and counter-intuitive wins. diff --git a/recipes/README.md b/recipes/README.md deleted file mode 100644 index a4c65f64..00000000 --- a/recipes/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Recipes - -Task-oriented how-to sheets for the AIDD Framework. Each recipe is a self-contained tutorial: a clear goal, prerequisites, and steps you can follow end to end. - -| Recipe | Goal | Level | -| --- | --- | --- | -| [Start a project](start-a-project.md) | Take a greenfield idea to a set-up project with its AIDD context | Beginner | -| [Ship a feature](ship-a-feature.md) | Take a feature from idea to a reviewed, shipped PR | Beginner | -| [MCP installations](mcp-installation.md) | Decide when to use an MCP server vs a CLI, and wire up the recommended ones | Beginner | - -> More coming โ€” token optimisation, custom plugins, and others. - -## Contributing a recipe - -Recipes follow a shared template (title ยท goal ยท level ยท time ยท prerequisites ยท steps ยท verify ยท related). Use [`/aidd-context:12-cook`](../plugins/aidd-context/skills/12-cook/SKILL.md) to `list` or `upsert` a recipe from the canonical template, then open a PR. See [`CONTRIBUTING.md`](../CONTRIBUTING.md). diff --git a/recipes/mcp-installation.md b/recipes/mcp-installation.md deleted file mode 100644 index 1acf0fc0..00000000 --- a/recipes/mcp-installation.md +++ /dev/null @@ -1,53 +0,0 @@ -# MCP installations - -> **Goal:** Decide when to use an MCP server vs a CLI, and wire up the recommended ones. - -| | | -| --- | --- | -| **Level** | Beginner | -| **Time** | ~10 min | -| **Prerequisites** | An AI assistant (Claude Code); the CLI for the service when one exists (`gh`, `acli`, โ€ฆ) | - -## Why - -> **Prefer the CLI over MCP. It is more efficient.** - -An MCP server loads its full tool schema into **every** turn โ€” that bloats the context window and is less optimised. A CLI call costs a few tokens and returns only what you ask for. - -**Reach for MCP only when no CLI covers the service.** - -โš ๏ธ **Always verify your sources. Audit what you install before connecting any server.** - -## Recommended servers - -| Service | Official MCP | CLI alternative | Recommended | -| --- | --- | --- | --- | -| **GitHub** | [`api.githubcopilot.com/mcp/`](https://github.com/github/github-mcp-server) | [`gh`](https://cli.github.com/) | **CLI** โ€” `gh` covers issues, PRs, releases, API at a fraction of the context | -| **Atlassian** (Jira / Confluence) | [`mcp.atlassian.com/v1/mcp`](https://www.atlassian.com/platform/remote-mcp-server) | [`acli`](https://developer.atlassian.com/cloud/acli/guides/introduction/) (Jira only at GA) | **CLI** for Jira ยท **MCP** for Confluence (no CLI yet) | -| **Playwright** | [`@playwright/mcp`](https://github.com/microsoft/playwright-mcp) | [`npx playwright`](https://playwright.dev/docs/test-cli) + [official skill](https://claude.com/plugins/playwright) | **CLI** โ€” drives a real browser (`playwright open`, `codegen`, `--headed`). The skill wraps it | -| **Figma** | [`mcp.figma.com/mcp`](https://developers.figma.com/docs/figma-mcp-server/remote-server-installation/) | none for design data | **MCP** | -| **Notion** | [`mcp.notion.com/mcp`](https://developers.notion.com/guides/mcp/get-started-with-mcp) | none official | **MCP** | - -## Steps - -1. ๐Ÿ”Ž **Check for a CLI first** โ€” if the service has one (GitHub โ†’ `gh`, Jira โ†’ `acli`), install and authenticate it instead of an MCP server. -2. ๐Ÿ”Œ **If MCP is the only option**, add the server to your `.mcp.json`: - ```json - { - "mcpServers": { - "figma": { "url": "https://mcp.figma.com/mcp" } - } - } - ``` -3. ๐Ÿ›ก๏ธ **Audit the server** before connecting โ€” read its docs and the permissions it requests. -4. โœ… **Restart** your assistant so it picks up the new configuration. - -## Verify - -- The MCP tools appear in your assistant (e.g. `/mcp` in Claude Code lists connected servers). -- For a CLI, run a read-only command (`gh auth status`, `acli jira me`) and confirm it returns. - -## Related - -- [`docs/ARCHITECTURE.md`](../docs/ARCHITECTURE.md) โ€” how the framework is structured -- [Anthropic โ€” discover plugins](https://code.claude.com/docs/en/discover-plugins) diff --git a/recipes/ship-a-feature.md b/recipes/ship-a-feature.md deleted file mode 100644 index a23a4b86..00000000 --- a/recipes/ship-a-feature.md +++ /dev/null @@ -1,37 +0,0 @@ -<!-- Recipe contract: file is recipes/<kebab-slug>.md ยท Level โˆˆ {Beginner, Intermediate, Advanced} ยท Time prefixed with ~ ยท one idea per sentence, prefer removing over adding. --> - -# Ship a feature end to end - -> **Goal:** Take a feature from a rough idea to a reviewed, shipped pull request with the AIDD flow. - -| | | -| ----------------- | ------------------------------------------------------------ | -| **Level** | Beginner | -| **Time** | ~varies with the feature | -| **Prerequisites** | AIDD installed; project set up ([Start a project](start-a-project.md)) | - -## Why - -The common loop, at a glance โ€” the exact commands to run so you never wonder what comes next. - -> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. - -## Steps - -1. ๐Ÿ’ก **Clarify**: `/aidd-refine:01-brainstorm` โ€” turn the rough idea into a precise request. -2. ๐Ÿ“‹ **Plan**: `/aidd-dev:01-plan` โ€” draft the phased technical plan. -3. ๐Ÿ”ง **Implement**: `/aidd-dev:02-implement` โ€” write the code, phase by phase. -4. ๐Ÿ” **Review**: `/aidd-dev:05-review` โ€” review the diff before it ships. -5. ๐Ÿ“ฆ **Commit**: `/aidd-vcs:01-commit` โ€” one atomic conventional commit. -6. โœ… **Pull request**: `/aidd-vcs:02-pull-request` โ€” open the PR. - -> One command for the whole loop: `/aidd-dev:00-sdlc` runs plan โ†’ implement โ†’ review โ†’ ship. - -## Verify - -- A pull request is open on your branch, with the diff reviewed and tests passing. - -## Related - -- [Start a project](start-a-project.md) โ€” greenfield setup before your first feature. -- `/aidd-context:00-onboard` โ€” guidance on what to run next at any point. diff --git a/recipes/start-a-project.md b/recipes/start-a-project.md deleted file mode 100644 index 5fd98f72..00000000 --- a/recipes/start-a-project.md +++ /dev/null @@ -1,34 +0,0 @@ -<!-- Recipe contract: file is recipes/<kebab-slug>.md ยท Level โˆˆ {Beginner, Intermediate, Advanced} ยท Time prefixed with ~ ยท one idea per sentence, prefer removing over adding. --> - -# Start a project (greenfield) - -> **Goal:** Take a greenfield idea to a set-up project with its AIDD context, ready for the first feature. - -| | | -| ----------------- | ------------------------------ | -| **Level** | Beginner | -| **Time** | ~30 min | -| **Prerequisites** | AIDD installed in your AI tool | - -## Why - -The greenfield sequence, at a glance โ€” from a raw idea to a project the AIDD flow can build on. - -> Prefer a guided walkthrough? `/aidd-context:00-onboard` inspects your project and routes you step by step instead of running the sequence by hand. - -## Steps - -1. ๐Ÿ’ก **Brainstorm the idea**: `/aidd-refine:01-brainstorm` โ€” sharpen the raw idea into a precise request. -2. ๐Ÿ“„ **Draft the PRD**: `/aidd-pm:03-prd` โ€” turn the idea into a structured product requirements document. -3. ๐Ÿ—๏ธ **Design the architecture**: `/aidd-context:01-bootstrap` โ€” validate a stack through Q&A; outputs an `INSTALL.md`. -4. ๐Ÿง  **Build project memory**: `/aidd-context:02-project-memory` โ€” create the memory bank and AI context files. -5. ๐Ÿš€ **Ship the first feature**: follow [Ship a feature](ship-a-feature.md). - -## Verify - -- `aidd_docs/memory/` holds the memory files, and an `INSTALL.md` describes the chosen stack. - -## Related - -- [Ship a feature](ship-a-feature.md) โ€” the per-feature loop once the project is set up. -- `/aidd-context:00-onboard` โ€” re-run any time to see where the project sits.