From 37d3d0736edd00ff7016c1ff504966c6e4f6da75 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 18 Jun 2026 22:14:45 +0200 Subject: [PATCH 01/23] feat(aidd-context): add research and apply actions to cook skill Extend 12-cook from author-only to a fuller loop: - 03-research: refine the target recipe via a checklist, fan out one agent per scouting angle, then present alternatives / coverage gaps / counter-intuitive wins plus a recommendation. Ephemeral, never writes. - 04-apply: execute an existing recipe against the project via an agent that tracks the steps as a todo list and confirms before mutating. - upsert: qualitative overlap guard (none/partial/high) that suggests updating an existing recipe instead of creating a duplicate. - recipe-template: steps become "#### N)" headings with what/why, actionable how-bullets, and a mandatory concrete example (command with output, snippet, or screenshot/video). New references/assets: research-playbook, refine-goal-checklist, research-checklist. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 8 +++-- plugins/aidd-context/skills/12-cook/SKILL.md | 22 ++++++++---- .../skills/12-cook/actions/02-upsert.md | 6 ++-- .../skills/12-cook/actions/03-research.md | 30 ++++++++++++++++ .../skills/12-cook/actions/04-apply.md | 23 ++++++++++++ .../skills/12-cook/assets/recipe-template.md | 35 ++++++++++++++++--- .../12-cook/assets/refine-goal-checklist.md | 12 +++++++ .../12-cook/assets/research-checklist.md | 9 +++++ .../12-cook/references/research-playbook.md | 28 +++++++++++++++ 9 files changed, 158 insertions(+), 15 deletions(-) create mode 100644 plugins/aidd-context/skills/12-cook/actions/03-research.md create mode 100644 plugins/aidd-context/skills/12-cook/actions/04-apply.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/research-checklist.md create mode 100644 plugins/aidd-context/skills/12-cook/references/research-playbook.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 1783a184..74eecb41 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -189,6 +189,10 @@ 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` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.md) | - | +| `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.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 them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe".` | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index f1a41387..996d0038 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,7 +1,7 @@ --- 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 the project's recipes/ how-to sheets: list them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe". +argument-hint: list | upsert | research | apply --- # Cook @@ -10,14 +10,22 @@ 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. Before running an action, read its file in `actions/`, not only the table or assets. +## References + +- `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). + ## 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/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. +- `assets/research-checklist.md`: the done-when gate `research` clears before drafting. 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..9f2dd880 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -13,10 +13,12 @@ The recipe file at `recipes/.md`, filled from the template, with its row a ## Process 1. Derive a kebab-case `` from the topic → `recipes/.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 `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. +2. If `recipes/.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. +3. If it exists, update in place; else scaffold from the template. +4. 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 `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test - `recipes/.md` exists and matches the template, every section present, no `<...>` placeholder left. - `recipes/README.md` carries a row for ``: its title linked, plus the goal and level. +- A new recipe that highly overlaps an existing one 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..3f700028 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -0,0 +1,30 @@ +# 03 - Research alternatives + +Refine the target recipe with a checklist, then scout for the highest-value insights and propose them as sorted lists. + +## Input + +The recipe or topic to modernize. If a recipe, its `recipes/.md` holds the current approach and coverage. + +## Output + +Three parts, then a recommendation: + +1. An alternatives table `| Alternative | What it is | Pros | Cons | Source |`, 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. + +Ephemeral: nothing is written under `recipes/`. + +## Process + +1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. +2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims corroborated. +4. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, then state a recommendation and why. +5. **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. +- 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..45e00c4f --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -0,0 +1,23 @@ +# 04 - Apply recipe + +Execute an existing recipe against the current project by spawning an agent that works through its steps as a tracked todo list, confirming with the user. + +## Input + +The recipe to apply, named by slug or topic. + +## Output + +The recipe's `## Steps` carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. + +## Process + +1. **Locate.** Resolve the recipe to `recipes/.md` and read it. Run `list` first when the recipe is unnamed. +2. **Plan.** Turn each `## Steps` item into one todo entry. +3. **Confirm.** Show the user the plan and ask for confirmation before any change. +4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. +5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. + +## Test + +- Applying a recipe produces a todo list mirroring its `## Steps`, asks for confirmation before executing, and runs the `## Verify` checks at the end. 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..bf3f98e9 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,4 +1,4 @@ - + # @@ -16,9 +16,36 @@ ## Steps -1. 📋 ****: -2. 🔧 ****: -3. ✅ ****: +#### 1) + + + +- +- + +```bash +$ + +``` + +#### 2) + + + +- +- + +``` + +``` + +#### 3) + + + +- + +![]() ## Verify diff --git a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md new file mode 100644 index 00000000..ba2e17f4 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md @@ -0,0 +1,12 @@ + + +# 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 / Advanced. +- [ ] **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** — how insights are categorized: by level, by sub-topic, or by use-case. +- [ ] **Counter-intuitive wins** — leave room for surprising tips that outperform the obvious default. 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 @@ + + +# 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/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md new file mode 100644 index 00000000..24c16242 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -0,0 +1,28 @@ + + +# Research playbook + +Guidance for `03-research`: the angles to scout and the criteria each candidate must clear. Define the target with `assets/refine-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. + +## Reporting + +- Return each candidate with its angle, level, value, and a one-line source. +- 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. From 25a8124a7567e653a7347d076e05a774259cc44d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 07:45:45 +0200 Subject: [PATCH 02/23] feat(aidd-context): verify each research candidate before presenting Add a Verify step to cook's 03-research: after curation, spawn one agent per surviving candidate to confirm it exists, capture its official link, and record its latest state. Drop anything that cannot be confirmed against an official source. This makes the checklist's "Confirm claims" real and guards the recipe against hallucinated tools or methods. Co-Authored-By: Claude Opus 4.8 --- .../skills/12-cook/actions/03-research.md | 15 ++++++++------- .../12-cook/references/research-playbook.md | 15 ++++++++++++--- 2 files changed, 20 insertions(+), 10 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md index 3f700028..e5b67568 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -1,6 +1,6 @@ # 03 - Research alternatives -Refine the target recipe with a checklist, then scout for the highest-value insights and propose them as sorted lists. +Refine the target recipe with a checklist, scout for the highest-value insights, verify each one exists, and propose them as sorted lists. ## Input @@ -10,21 +10,22 @@ The recipe or topic to modernize. If a recipe, its `recipes/.md` holds the Three parts, then a recommendation: -1. An alternatives table `| Alternative | What it is | Pros | Cons | Source |`, sorted by value. +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. -Ephemeral: nothing is written under `recipes/`. +Every presented item is confirmed to exist, with its latest state and official link. Ephemeral: nothing is written under `recipes/`. ## Process 1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. 2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. -3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims corroborated. -4. **Present.** Render the alternatives table, the coverage-gaps list, and the counter-intuitive wins list, then state a recommendation and why. -5. **Hand off.** If the user picks insights to keep, route to `upsert` to fold them into the recipe. +3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. +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. This clears the checklist's `Confirm claims`. +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. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims confirmed. +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. -- The research checklist clears (gaps filled, unknowns surfaced, claims confirmed) before any hand-off to `upsert`. +- Every presented item carries an official link and was confirmed to exist; unverifiable candidates are dropped. diff --git a/plugins/aidd-context/skills/12-cook/references/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index 24c16242..062d45f1 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -1,8 +1,8 @@ - + # Research playbook -Guidance for `03-research`: the angles to scout and the criteria each candidate must clear. Define the target with `assets/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. +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/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. ## Angles to cover @@ -21,8 +21,17 @@ Spawn one agent per angle so coverage stays wide: - **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. +- Drop any candidate that cannot be confirmed against an official source. + ## Reporting -- Return each candidate with its angle, level, value, and a one-line source. +- 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. From 60f0618ee50e73345a035be5b8abbb051712fb28 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 07:48:45 +0200 Subject: [PATCH 03/23] docs(framework): add token optimization recipe Add recipes/token-optimization.md: a ranked list of token-saving tips for AI coding assistants (measure first, trim CLAUDE.md, caveman, RTK/SNIP, CLI over MCP, progressive disclosure, compact, model routing, cap thinking), each tip in the new template format with a concrete example and an official link verified to exist. Register it in the recipes index. Co-Authored-By: Claude Opus 4.8 --- recipes/README.md | 3 +- recipes/token-optimization.md | 132 ++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 1 deletion(-) create mode 100644 recipes/token-optimization.md diff --git a/recipes/README.md b/recipes/README.md index a4c65f64..b79bbf4d 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -7,8 +7,9 @@ Task-oriented how-to sheets for the AIDD Framework. Each recipe is a self-contai | [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 | +| [Token optimization for AI IDEs](token-optimization.md) | Cut token usage and cost in AI coding assistants without losing output quality | Intermediate | -> More coming — token optimisation, custom plugins, and others. +> More coming — custom plugins, and others. ## Contributing a recipe diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md new file mode 100644 index 00000000..b5483264 --- /dev/null +++ b/recipes/token-optimization.md @@ -0,0 +1,132 @@ +# Token optimization for AI IDEs + +> **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. + +| | | +| ----------------- | ---------------------------------------------------------------------------- | +| **Level** | Intermediate | +| **Time** | ~15 min | +| **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | + +## Why + +Tokens are the bill. Every turn re-sends your context window — instructions, file reads, command output, the model's own narration — and you pay for all of it, every time. Most of it is waste: filler prose, noisy logs, stale context, oversized instruction files. The tips below attack each source. Stack them and large savings are realistic; every percentage here is **as reported by the tool**, not an independent benchmark. + +> **Measure before you optimise.** You cannot cut what you do not see. + +## Best tips + +Ranked by impact-to-effort. Start at the top. + +#### 1) Measure first + +You cannot improve what you do not track, and the bill is rarely where you think — cache reads usually dominate, not generation. + +- In Claude Code: `/context` shows what fills the window, `/cost` shows the session cost and plan usage, `/insights` reports your session patterns and friction points. +- For a per-prompt breakdown across every session, use [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code). + +```bash +$ uvx --from prompt-analytics-for-claude-code prompt-analytics summary +# per-prompt tokens & cost from your local logs — cache reads dominate the total +``` + +#### 2) Trim your instruction file + +`CLAUDE.md` (or `.github/copilot-instructions.md`) ships in **every** turn, so each wasted line is taxed on every message. + +- Keep it short; add explicit conciseness rules. +- Drop-in ruleset: [`drona23/claude-token-efficient`](https://github.com/drona23/claude-token-efficient) (savings vary by model; measure your own). + +```md +# CLAUDE.md +- Terse answers. No preamble, no "Let me…", no closing summary. +- Keep verbatim: code, quoted errors, security warnings. Cut the rest. +``` + +#### 3) Make the agent talk less + +Output is repetition — "Let me explain…", "Here's a summary…". You pay to generate every word. + +- The [`caveman`](https://github.com/JuliusBrussee/caveman) skill forces short, filler-free replies (reported ~65% output-token cut, code and data intact). Auto-detects 30+ agents. + +```text +before: "Great question! Let me walk you through each of the steps involved…" +after: "3 steps:" +``` + +#### 4) Filter noisy command output + +Test runs, installs, and build logs flood the context with lines the model never needs. + +- A CLI proxy strips them before they land: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). Both report 60–90% on noisy output, zero overhead when no filter matches. + +```bash +$ rtk proxy npm test +# full build log in → only failures + final summary kept +``` + +#### 5) Prefer CLI over MCP + +An MCP server loads its full tool schema into **every** turn; a CLI call costs a few tokens only when you use it. + +- Reach for the CLI when one exists; keep MCP for what truly needs it. See [`mcp-installation.md`](mcp-installation.md). + +```bash +$ gh pr list # a few tokens per call +# vs a GitHub MCP server: its whole schema rides along every turn +``` + +#### 6) Use progressive disclosure + +Don't paste big procedural docs into context. Load knowledge only when the task needs it. + +- Install an AIDD framework so skills, rules, and runbooks load on demand instead of riding along every turn. + +```text +skill description matched → its steps load +no match → 0 tokens spent +``` + +#### 7) Compact deliberately + +Auto-compaction fires late and may drop what you wanted kept. + +- Run `/compact` around 60–70% context, passing focus instructions for what to retain. + +```bash +$ /compact keep the repro steps and the failing test; drop the file dumps +``` + +#### 8) Route by difficulty + +The top model on a routine task is wasted spend. + +- Send research and routine work to a cheaper/faster model or a fresh subagent context; reserve the strongest model for the hard reasoning. + +```text +research / boilerplate → small model or subagent +architecture / tricky bug → top model +``` + +#### 9) Cap extended thinking + +Extended reasoning can silently add thousands of tokens per turn on tasks that don't need it. + +- Control it with `MAX_THINKING_TOKENS` in your settings — set `0` to turn extended thinking off when you don't need it. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). + +```bash +# settings.json (env) +"MAX_THINKING_TOKENS": "0" # disable extended thinking for routine work +``` + +## Verify + +- Run `/cost` (or `prompt-analytics summary`) before and after a typical task — the token count should drop measurably. +- `/context` shows your instruction file and tool schemas taking a smaller share of the window. +- A noisy command (test suite, `npm install`) routed through RTK or SNIP returns far fewer lines than the raw run. + +## Related + +- [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency +- [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) +- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) From 149deeb67425f117f682db12ac728b362598c9ce Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 08:12:14 +0200 Subject: [PATCH 04/23] refactor(aidd-context): extract recipe contract and tighten cook template Move the recipe authoring rules out of the template's HTML comment into references/recipe-contract.md, cited by SKILL.md and upsert. The template keeps only the scaffold. - Steps heading carries the goal ("## Steps to ") and each step opens with an emoji. - Step how-bullets follow where-it-is -> install-from-URL -> how-to-use, benefit-first and filler-free. - "## Why" is short, keyword-led, and bold. - SKILL.md description is shorter and high-level, triggered on "recipe" / "cook" / "/cook". Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 3 ++- plugins/aidd-context/skills/12-cook/SKILL.md | 5 ++-- .../skills/12-cook/actions/02-upsert.md | 6 ++--- .../skills/12-cook/actions/04-apply.md | 6 ++--- .../skills/12-cook/assets/recipe-template.md | 23 +++++++++--------- .../12-cook/references/recipe-contract.md | 24 +++++++++++++++++++ 6 files changed, 46 insertions(+), 21 deletions(-) create mode 100644 plugins/aidd-context/skills/12-cook/references/recipe-contract.md diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 74eecb41..115d56b6 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -194,5 +194,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [recipe-template.md](skills/12-cook/assets/recipe-template.md) | - | | `assets` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.md) | - | | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - | +| `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 them as a table, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run a recipe".` | +| `-` | [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".` | diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index 996d0038..19caf85c 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/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, create or update one from the canonical template, research modern alternatives for a recipe, or apply a recipe to the project. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe", "research a recipe", "modernize a recipe", "apply a recipe", "run 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". argument-hint: list | upsert | research | apply --- @@ -22,10 +22,11 @@ Before running an action, read its file in `actions/`, not only the table or ass ## References +- `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. - `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). ## 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/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. - `assets/research-checklist.md`: the done-when gate `research` clears before drafting. 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 9f2dd880..a85fc79b 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,6 +1,6 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/.md`, scaffolded from `@../assets/recipe-template.md`. +Create or update one recipe at `recipes/.md`, scaffolded from `@../assets/recipe-template.md` and following the rules in `@../references/recipe-contract.md`. ## Input @@ -14,11 +14,11 @@ The recipe file at `recipes/.md`, filled from the template, with its row a 1. Derive a kebab-case `` from the topic → `recipes/.md`. 2. If `recipes/.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. -3. If it exists, update in place; else scaffold from the template. +3. If it exists, update in place; else scaffold from the template. Apply `@../references/recipe-contract.md` to every section. 4. 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 `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test -- `recipes/.md` exists and matches the template, every section present, no `<...>` placeholder left. +- `recipes/.md` exists and follows `@../references/recipe-contract.md`: every section present, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. - `recipes/README.md` carries a row for ``: its title linked, plus the goal and level. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index 45e00c4f..b337eea5 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -8,16 +8,16 @@ The recipe to apply, named by slug or topic. ## Output -The recipe's `## Steps` carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. +The recipe's steps carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. ## Process 1. **Locate.** Resolve the recipe to `recipes/.md` and read it. Run `list` first when the recipe is unnamed. -2. **Plan.** Turn each `## Steps` item into one todo entry. +2. **Plan.** Turn each step under the recipe's steps heading (`## Steps to …`) into one todo entry. 3. **Confirm.** Show the user the plan and ask for confirmation before any change. 4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. 5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. ## Test -- Applying a recipe produces a todo list mirroring its `## Steps`, asks for confirmation before executing, and runs the `## Verify` checks at the end. +- Applying a recipe produces a todo list mirroring the recipe's steps, asks for confirmation before executing, and runs the `## Verify` checks at the end. 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 bf3f98e9..86bfe0d2 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,5 +1,3 @@ - - # > **Goal:** @@ -12,25 +10,26 @@ ## Why - + -## Steps +## Steps to -#### 1) +#### 1) - + -- -- +- +- +- ```bash $ ``` -#### 2) +#### 2) - + - - @@ -39,9 +38,9 @@ $ ``` -#### 3) +#### 3) - + - 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..e9f13049 --- /dev/null +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -0,0 +1,24 @@ + + +# Recipe contract + +Rules for every `recipes/.md` the skill writes. + +## File + +- Path: `recipes/.md`. +- `Level` is one of Beginner, Intermediate, Advanced. `Time` is prefixed with `~`. + +## 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. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no more. + +## Steps + +- The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. +- How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. +- Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Link to a reference when applicable. From ee434e35c61997c9a66381476d48697fd00c8b29 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 13:37:13 +0200 Subject: [PATCH 05/23] fix(aidd-context): repair 12-cook SKILL.md YAML frontmatter The description contained an unquoted "sheets: list" colon, which YAML parses as a mapping value and rejects ("mapping values are not allowed here"), breaking the skill's frontmatter. Replace the colon with a dash. The bug pre-dated this branch (same colon on main). Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/12-cook/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 115d56b6..8ef4e301 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -196,4 +196,4 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [research-checklist.md](skills/12-cook/assets/research-checklist.md) | - | | `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".` | +| `-` | [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/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index 19caf85c..a2526b19 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/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, create or update, research, or apply a recipe. Use for "recipe", "cook", "/cook", "list/new/update/research/apply a recipe". +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 --- From d19a5cf4b6428e3d437b0edc36e2f75326cc7b02 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 14:13:43 +0200 Subject: [PATCH 06/23] refactor(aidd-context): refine cook recipe structure and apply R13 to cook MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback on the cook skill, plus the new includes convention: - Recipe template drops the Time field, groups steps under three level subheadings (Beginner / Intermediate / Expert), and aligns the Level enum to Expert. - upsert now runs `research` (03) first for any new or substantial recipe and drafts only from its verified results, never from memory — the "always research" rule was being skipped as a routing note. - Apply R13 (explicit, scoped includes): the action-specific research aids move out of SKILL.md and are cited from 03-research in fenced blocks; refine-goal-checklist is renamed research-goal-checklist; SKILL.md lists only the global recipe-template and recipe-contract. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/CATALOG.md | 2 +- plugins/aidd-context/skills/12-cook/SKILL.md | 3 --- .../skills/12-cook/actions/02-upsert.md | 21 ++++++++++----- .../skills/12-cook/actions/03-research.md | 26 +++++++++++++++---- .../skills/12-cook/assets/recipe-template.md | 9 +++++-- ...hecklist.md => research-goal-checklist.md} | 6 ++--- .../12-cook/references/recipe-contract.md | 5 ++-- 7 files changed, 49 insertions(+), 23 deletions(-) rename plugins/aidd-context/skills/12-cook/assets/{refine-goal-checklist.md => research-goal-checklist.md} (70%) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 8ef4e301..67166a74 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -192,8 +192,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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` | [refine-goal-checklist.md](skills/12-cook/assets/refine-goal-checklist.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) | - | | `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 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/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index a2526b19..035b55eb 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -23,10 +23,7 @@ Before running an action, read its file in `actions/`, not only the table or ass ## References - `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. -- `references/research-playbook.md`: the scouting angles and per-candidate criteria `research` applies (freshness, community signal, tips). ## Assets - `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. -- `assets/refine-goal-checklist.md`: the checklist `research` fills with the user to define the target recipe. -- `assets/research-checklist.md`: the done-when gate `research` clears before drafting. 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 a85fc79b..bc0101af 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -1,10 +1,15 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/.md`, scaffolded from `@../assets/recipe-template.md` and following the rules in `@../references/recipe-contract.md`. +Create or update one recipe at `recipes/.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 (level, prerequisites, steps, verify, related) before writing. ## Output @@ -12,13 +17,15 @@ The recipe file at `recipes/.md`, filled from the template, with its row a ## Process -1. Derive a kebab-case `` from the topic → `recipes/.md`. -2. If `recipes/.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. -3. If it exists, update in place; else scaffold from the template. Apply `@../references/recipe-contract.md` to every section. -4. 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 `.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 `` from the topic → `recipes/.md`. +3. If `recipes/.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 | Goal | Level |`: link the title to `.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. ## Test -- `recipes/.md` exists and follows `@../references/recipe-contract.md`: every section present, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. +- A new or substantially-updated recipe is drafted from `research` results, not from memory. +- `recipes/.md` exists and follows the recipe contract: every section present, steps grouped under the three level subheadings, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. - `recipes/README.md` carries a row for ``: its title linked, plus the goal and level. - A new recipe that highly overlaps an existing one 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 index e5b67568..e6c8695b 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -18,14 +18,30 @@ Every presented item is confirmed to exist, with its latest state and official l ## Process -1. **Refine.** Fill `@assets/refine-goal-checklist.md` with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.md` first when the recipe exists. Run `list` when it is unnamed. -2. **Fan out.** Spawn one agent per angle in `@references/research-playbook.md` via the `Task` tool. Each applies the playbook criteria (freshness, community signal, tips), pushes for the most insights it can, and includes counter-intuitive ones with evidence. Each returns candidates with sources. -3. **Curate.** Dedupe the candidates. Drop anything that neither beats nor extends the recipe. Sort each bucket by value. -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. This clears the checklist's `Confirm claims`. -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. Clear `@assets/research-checklist.md`: gaps filled, unknowns surfaced, claims confirmed. +1. **Refine.** Fill the goal checklist with the user until the target is precise: outcome, level, scope, grouping. Read `recipes/.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`. 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 86bfe0d2..d4c30f4e 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -4,8 +4,7 @@ | | | | ----------------- | ---------------------------------------- | -| **Level** | | -| **Time** | ~ min | +| **Level** | | | **Prerequisites** | | ## Why @@ -14,6 +13,8 @@ ## Steps to +### 🟢 Beginner + #### 1) @@ -27,6 +28,8 @@ $ ``` +### 🟡 Intermediate + #### 2) @@ -38,6 +41,8 @@ $ ``` +### 🔴 Expert + #### 3) diff --git a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md similarity index 70% rename from plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md rename to plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md index ba2e17f4..3ad21d32 100644 --- a/plugins/aidd-context/skills/12-cook/assets/refine-goal-checklist.md +++ b/plugins/aidd-context/skills/12-cook/assets/research-goal-checklist.md @@ -1,12 +1,12 @@ - + # 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 / Advanced. +- [ ] **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** — how insights are categorized: by level, by sub-topic, or by use-case. +- [ ] **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 index e9f13049..981a2ef1 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -7,7 +7,7 @@ Rules for every `recipes/.md` the skill writes. ## File - Path: `recipes/.md`. -- `Level` is one of Beginner, Intermediate, Advanced. `Time` is prefixed with `~`. +- `Level` is one of Beginner, Intermediate, Expert. ## Writing @@ -18,7 +18,8 @@ Rules for every `recipes/.md` the skill writes. ## Steps - The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. -- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. +- Group the steps under three level subheadings, in order: `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert`. Put each step under the level it fits; drop a level that has no step. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously across levels. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. - Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. - Link to a reference when applicable. From 8d37b75d4916fe66be213aa58e2320eefaba45fd Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 19 Jun 2026 14:27:55 +0200 Subject: [PATCH 07/23] refactor(aidd-context): make recipe level subheadings optional Level grouping was effectively mandatory. Make the contract state it is optional: group steps under Beginner/Intermediate/Expert only when the recipe spans difficulty levels and grouping helps; a short or single-level recipe lists its steps directly. Relax the upsert Test accordingly. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/12-cook/actions/02-upsert.md | 2 +- .../aidd-context/skills/12-cook/references/recipe-contract.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) 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 bc0101af..b9419517 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -26,6 +26,6 @@ The recipe file at `recipes/.md`, filled from the template, with its row a ## Test - A new or substantially-updated recipe is drafted from `research` results, not from memory. -- `recipes/.md` exists and follows the recipe contract: every section present, steps grouped under the three level subheadings, each step a `#### N)` emoji heading with an example, no `<...>` placeholder left. +- `recipes/.md` exists and follows the recipe contract: every section present, each step a `#### N)` emoji heading with an example, with level subheadings used only when they help, no `<...>` placeholder left. - `recipes/README.md` carries a row for ``: its title linked, plus the goal and level. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 981a2ef1..ac6600c2 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -18,8 +18,8 @@ Rules for every `recipes/.md` the skill writes. ## Steps - The steps section heading is named after the goal: `## Steps to `, never a bare `## Steps`. -- Group the steps under three level subheadings, in order: `### 🟢 Beginner`, `### 🟡 Intermediate`, `### 🔴 Expert`. Put each step under the level it fits; drop a level that has no step. -- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously across levels. +- Each step is a `#### N) Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. - Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- 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. From dd9290684821dceb4ebf8346ba63b317efaf8175 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 12:53:16 +0200 Subject: [PATCH 08/23] docs(framework): conform token-optimization recipe to recipe contract Align the recipe with references/recipe-contract.md: drop the Time row (no longer in the template), name the section "Steps to " instead of a bare Steps, remove the "ranked by impact" filler line, and give each step how-bullets plus a concrete example. Co-Authored-By: Claude Opus 4.8 (1M context) --- recipes/token-optimization.md | 109 ++++++++++++++++++---------------- 1 file changed, 58 insertions(+), 51 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index b5483264..2e773c71 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -2,40 +2,38 @@ > **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. -| | | -| ----------------- | ---------------------------------------------------------------------------- | -| **Level** | Intermediate | -| **Time** | ~15 min | +| | | +| ----------------- | ---------------------------------------------------------------------------------- | +| **Level** | Intermediate | | **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | ## Why -Tokens are the bill. Every turn re-sends your context window — instructions, file reads, command output, the model's own narration — and you pay for all of it, every time. Most of it is waste: filler prose, noisy logs, stale context, oversized instruction files. The tips below attack each source. Stack them and large savings are realistic; every percentage here is **as reported by the tool**, not an independent benchmark. +**Token usage** is the bill. Every turn re-sends your whole **context window** — instructions, file reads, command output, narration — 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 output. -> **Measure before you optimise.** You cannot cut what you do not see. +## Steps to cut token usage -## Best tips +### 🟢 Beginner -Ranked by impact-to-effort. Start at the top. +#### 1) 📊 Measure first -#### 1) Measure first +You cannot cut what you cannot see, so find what fills the window before changing anything. -You cannot improve what you do not track, and the bill is rarely where you think — cache reads usually dominate, not generation. - -- In Claude Code: `/context` shows what fills the window, `/cost` shows the session cost and plan usage, `/insights` reports your session patterns and friction points. -- For a per-prompt breakdown across every session, use [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code). +- Built-in: run `/context`, `/cost`, and `/insights` in Claude Code. +- Cross-session detail: install [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and run it with `uvx`. ```bash $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary -# per-prompt tokens & cost from your local logs — cache reads dominate the total +# per-prompt tokens & cost from local logs — cache reads usually dominate ``` -#### 2) Trim your instruction file +#### 2) ✂️ Trim your instruction file -`CLAUDE.md` (or `.github/copilot-instructions.md`) ships in **every** turn, so each wasted line is taxed on every message. +Your instruction file ships every turn, so each cut line saves on every message. -- Keep it short; add explicit conciseness rules. -- Drop-in ruleset: [`drona23/claude-token-efficient`](https://github.com/drona23/claude-token-efficient) (savings vary by model; measure your own). +- It lives at `CLAUDE.md` (or `.github/copilot-instructions.md`). +- Cut it to essentials and add explicit conciseness rules. +- Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. ```md # CLAUDE.md @@ -43,76 +41,85 @@ $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 3) Make the agent talk less +#### 3) 🗜️ Compact deliberately + +Compacting on your terms keeps what matters instead of letting auto-compaction guess. + +- Watch context use and act around 60–70%. +- Run `/compact` with focus instructions naming what to keep. + +```bash +$ /compact keep the repro steps and the failing test; drop the file dumps +``` + +### 🟡 Intermediate + +#### 4) 🗣️ Make the agent talk less -Output is repetition — "Let me explain…", "Here's a summary…". You pay to generate every word. +Output is repetition you pay to generate, so cap the chatter. -- The [`caveman`](https://github.com/JuliusBrussee/caveman) skill forces short, filler-free replies (reported ~65% output-token cut, code and data intact). Auto-detects 30+ agents. +- Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). +- It forces short, filler-free replies (reported ~65% output cut, code intact). ```text -before: "Great question! Let me walk you through each of the steps involved…" +before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` -#### 4) Filter noisy command output +#### 5) 🧹 Filter noisy command output -Test runs, installs, and build logs flood the context with lines the model never needs. +Test, install, and build logs flood context with lines the model never needs. -- A CLI proxy strips them before they land: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). Both report 60–90% on noisy output, zero overhead when no filter matches. +- Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). +- Run noisy commands through it; it keeps only the signal (reported 60–90%). ```bash $ rtk proxy npm test # full build log in → only failures + final summary kept ``` -#### 5) Prefer CLI over MCP +#### 6) 🔌 Prefer CLI over MCP -An MCP server loads its full tool schema into **every** turn; a CLI call costs a few tokens only when you use it. +An MCP server loads its full schema every turn, while a CLI costs tokens only when called. -- Reach for the CLI when one exists; keep MCP for what truly needs it. See [`mcp-installation.md`](mcp-installation.md). +- Use the CLI when one exists (`gh`, `acli`, …); keep MCP for what has none. +- See [`mcp-installation.md`](mcp-installation.md). ```bash -$ gh pr list # a few tokens per call -# vs a GitHub MCP server: its whole schema rides along every turn +$ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along every turn ``` -#### 6) Use progressive disclosure +### 🔴 Expert -Don't paste big procedural docs into context. Load knowledge only when the task needs it. +#### 7) 📚 Use progressive disclosure -- Install an AIDD framework so skills, rules, and runbooks load on demand instead of riding along every turn. +Load knowledge only when the task needs it, instead of riding along every turn. + +- Install an AIDD framework so skills, rules, and runbooks load on demand. ```text skill description matched → its steps load no match → 0 tokens spent ``` -#### 7) Compact deliberately - -Auto-compaction fires late and may drop what you wanted kept. - -- Run `/compact` around 60–70% context, passing focus instructions for what to retain. - -```bash -$ /compact keep the repro steps and the failing test; drop the file dumps -``` - -#### 8) Route by difficulty +#### 8) 🎯 Route by difficulty -The top model on a routine task is wasted spend. +The top model on routine work is wasted spend. -- Send research and routine work to a cheaper/faster model or a fresh subagent context; reserve the strongest model for the hard reasoning. +- Send research and boilerplate to a cheaper model or a fresh subagent. +- Reserve the strongest model for hard reasoning. ```text research / boilerplate → small model or subagent architecture / tricky bug → top model ``` -#### 9) Cap extended thinking +#### 9) ✅ Cap extended thinking -Extended reasoning can silently add thousands of tokens per turn on tasks that don't need it. +Extended reasoning can silently add thousands of tokens on tasks that don't need it. -- Control it with `MAX_THINKING_TOKENS` in your settings — set `0` to turn extended thinking off when you don't need it. See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). +- Set `MAX_THINKING_TOKENS` to `0` for routine work. +- See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). ```bash # settings.json (env) @@ -121,9 +128,9 @@ Extended reasoning can silently add thousands of tokens per turn on tasks that d ## Verify -- Run `/cost` (or `prompt-analytics summary`) before and after a typical task — the token count should drop measurably. +- Run `/cost` before and after a typical task — the token count drops measurably. - `/context` shows your instruction file and tool schemas taking a smaller share of the window. -- A noisy command (test suite, `npm install`) routed through RTK or SNIP returns far fewer lines than the raw run. +- A noisy command routed through RTK or SNIP returns far fewer lines than the raw run. ## Related From ac6f8770a8dbea7520a479052f99767f4cb8ee20 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:46:08 +0200 Subject: [PATCH 09/23] docs(framework): split measure steps per tool and drop metadata table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Apply review of the token-optimization recipe: - Goal becomes a plain sentence (no blockquote). - Drop the Level/Prerequisites table; level now lives in the subheadings. - Split the bundled "Measure first" step into one step per tool (/context, /cost, /insights, an analytics tool) — one subheading per action. - Each measure step says how to use and read the command, and carries an example output; the analytics step uses a real prompt-analytics run (volumes rounded, cost omitted) showing cache reads dominate. Co-Authored-By: Claude Opus 4.8 --- recipes/token-optimization.md | 96 ++++++++++++++++++++++++++--------- 1 file changed, 73 insertions(+), 23 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 2e773c71..fa77823d 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -1,33 +1,83 @@ # Token optimization for AI IDEs -> **Goal:** Cut token usage and cost in AI coding assistants without losing output quality. +**Goal:** Cut token usage and cost in AI coding assistants without losing output quality. -| | | -| ----------------- | ---------------------------------------------------------------------------------- | -| **Level** | Intermediate | -| **Prerequisites** | An AI coding assistant (Claude Code, GitHub Copilot, Codex, Cursor, …); a terminal | +## Why optimize your tokens -## Why +**Token usage** is the bill — every turn re-sends your whole **context window** and you pay for it again. -**Token usage** is the bill. Every turn re-sends your whole **context window** — instructions, file reads, command output, narration — 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 output. +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) 📊 Measure first +#### 1) 🔎 See what fills the window — `/context` -You cannot cut what you cannot see, so find what fills the window before changing anything. +`/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. -- Built-in: run `/context`, `/cost`, and `/insights` in Claude Code. -- Cross-session detail: install [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and run it with `uvx`. +- Run `/context` in Claude Code. +- Read the grid and find the heavy blocks: tool schemas, instruction files, long file reads. +- Attack the biggest block first. -```bash +```text +$ /context + MCP tool schemas ████████████ 28% ← biggest, cut first + file reads ████████ 19% + CLAUDE.md ████ 9% + system + tools ███████████ … +(illustrative — paste your real /context here) +``` + +#### 2) 💸 Read the bill — `/cost` + +`/cost` tells you what a session actually costs and where the spend goes. + +- Run `/cost` (alias `/usage`). +- Read the breakdown by skill, subagent, and MCP server. +- 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 — paste your real /cost here) +``` + +#### 3) 🔍 Find your bad habits — `/insights` + +`/insights` analyses how you prompt — which is probably sub-optimal — so you fix the pattern, not one prompt. + +- What you repeat every session → move it into the knowledge base (`CLAUDE.md`, rules). +- Counter-intuitive habits you never noticed → surfaced so you can drop them. + +```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 — paste your real /insights here) +``` + +#### 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. + +- Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). +- Run one against your local history — no setup, it parses `~/.claude`. +- The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. + +```text $ uvx --from prompt-analytics-for-claude-code prompt-analytics summary -# per-prompt tokens & cost from local logs — cache reads usually dominate + Input tokens ~8M + Output tokens ~22M + Cache read tokens ~4.5B ← dominates the total + Source: live parse of ~/.claude/projects +(real run, token volumes rounded; cost figures omitted) ``` -#### 2) ✂️ Trim your instruction file +#### 5) ✂️ Trim your instruction file Your instruction file ships every turn, so each cut line saves on every message. @@ -41,20 +91,20 @@ Your instruction file ships every turn, so each cut line saves on every message. - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 3) 🗜️ Compact deliberately +#### 6) 🗜️ Compact deliberately Compacting on your terms keeps what matters instead of letting auto-compaction guess. - Watch context use and act around 60–70%. - Run `/compact` with focus instructions naming what to keep. -```bash +```text $ /compact keep the repro steps and the failing test; drop the file dumps ``` ### 🟡 Intermediate -#### 4) 🗣️ Make the agent talk less +#### 7) 🗣️ Make the agent talk less Output is repetition you pay to generate, so cap the chatter. @@ -66,7 +116,7 @@ before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` -#### 5) 🧹 Filter noisy command output +#### 8) 🧹 Filter noisy command output Test, install, and build logs flood context with lines the model never needs. @@ -78,7 +128,7 @@ $ rtk proxy npm test # full build log in → only failures + final summary kept ``` -#### 6) 🔌 Prefer CLI over MCP +#### 9) 🔌 Prefer CLI over MCP An MCP server loads its full schema every turn, while a CLI costs tokens only when called. @@ -91,7 +141,7 @@ $ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along ever ### 🔴 Expert -#### 7) 📚 Use progressive disclosure +#### 10) 📚 Use progressive disclosure Load knowledge only when the task needs it, instead of riding along every turn. @@ -102,7 +152,7 @@ skill description matched → its steps load no match → 0 tokens spent ``` -#### 8) 🎯 Route by difficulty +#### 11) 🎯 Route by difficulty The top model on routine work is wasted spend. @@ -114,7 +164,7 @@ research / boilerplate → small model or subagent architecture / tricky bug → top model ``` -#### 9) ✅ Cap extended thinking +#### 12) ✅ Cap extended thinking Extended reasoning can silently add thousands of tokens on tasks that don't need it. @@ -136,4 +186,4 @@ Extended reasoning can silently add thousands of tokens on tasks that don't need - [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency - [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) -- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) +- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`ccusage`](https://www.npmjs.com/package/ccusage) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) From 308e0a0fdfed859eff97fabf047fe183df955edc Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:51:06 +0200 Subject: [PATCH 10/23] docs(framework): drop the Goal label from token-optimization The recipe opens with a plain description sentence, no "Goal:" label. Co-Authored-By: Claude Opus 4.8 --- recipes/token-optimization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index fa77823d..0a988360 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -1,6 +1,6 @@ # Token optimization for AI IDEs -**Goal:** Cut token usage and cost in AI coding assistants without losing output quality. +Cut token usage and cost in AI coding assistants without losing output quality. ## Why optimize your tokens From 12229cd35f8b483fbb0d2e7928b6499d92c560aa Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Sat, 20 Jun 2026 17:51:06 +0200 Subject: [PATCH 11/23] refactor(aidd-context): recipe header = description sentence, no table MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rules extracted from the token-optimization recipe review: - A recipe opens with the H1 title then one plain description sentence — no "Goal:" label, no blockquote, no metadata table. list/upsert parse that sentence; the index becomes `| Recipe | Description |` (Level was dropped, level now lives only in the optional subheadings). - One step = one action; never bundle several tools or commands under a single heading. - Every step's example shows real command output (from docs or by running it); the research playbook now requires capturing a real example and marking interactive output for the human to paste. - `## Why` is one idea per line. Co-Authored-By: Claude Opus 4.8 --- plugins/aidd-context/skills/12-cook/actions/01-list.md | 10 +++++----- .../aidd-context/skills/12-cook/actions/02-upsert.md | 8 ++++---- .../skills/12-cook/assets/recipe-template.md | 9 ++------- .../skills/12-cook/references/recipe-contract.md | 7 ++++--- .../skills/12-cook/references/research-playbook.md | 3 ++- 5 files changed, 17 insertions(+), 20 deletions(-) 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..561fd1e2 100644 --- a/plugins/aidd-context/skills/12-cook/actions/01-list.md +++ b/plugins/aidd-context/skills/12-cook/actions/01-list.md @@ -5,9 +5,9 @@ List every recipe under `recipes/` at the project root as a table, excluding `RE ## Output ```md -| Recipe | Goal | Level | -| --- | --- | --- | -| [](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.` @@ -15,10 +15,10 @@ One row per `recipes/*.md`, sorted by file name. If `recipes/` is absent or empt ## 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. 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 b9419517..e7b6f360 100644 --- a/plugins/aidd-context/skills/12-cook/actions/02-upsert.md +++ b/plugins/aidd-context/skills/12-cook/actions/02-upsert.md @@ -9,7 +9,7 @@ Create or update one recipe at `recipes/<slug>.md`, scaffolded from the recipe t ## Input -The recipe topic. Ask for any missing field (level, prerequisites, steps, verify, related) before writing. +The recipe topic. Ask for any missing field (description, steps, verify, related) before writing. ## Output @@ -21,11 +21,11 @@ The recipe file at `recipes/<slug>.md`, filled from the template, with its row a 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 | Goal | Level |`: link the title to `<slug>.md` (relative), copy the `> **Goal:**` text, and copy the **Level**. Same columns `list` emits. +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 - A new or substantially-updated recipe is drafted from `research` results, not from memory. -- `recipes/<slug>.md` exists and follows the recipe contract: every section present, each step a `#### N)` emoji heading with an example, with level subheadings used only when they help, no `<...>` placeholder left. -- `recipes/README.md` carries a row for `<slug>`: its title linked, plus the goal and level. +- `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. +- `recipes/README.md` carries a row for `<slug>`: its title linked, plus the one-sentence description. - A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. 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 d4c30f4e..a60cb11d 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -1,15 +1,10 @@ # <Recipe title> -> **Goal:** <one line stating the outcome the reader achieves> - -| | | -| ----------------- | ---------------------------------------- | -| **Level** | <Beginner \| Intermediate \| Expert> | -| **Prerequisites** | <what the reader needs first, or "None"> | +<One sentence describing what this recipe gets the reader.> ## Why -<Short and benefit-first. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no filler.> +<Short and benefit-first, one idea per line. Lead with the keywords a reader would search, **bold** the key terms.> ## Steps to <the outcome the reader achieves> diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index ac6600c2..fb44bc84 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -7,19 +7,20 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. ## File - Path: `recipes/<kebab-slug>.md`. -- `Level` is one of Beginner, Intermediate, Expert. +- The recipe opens with the H1 title, then one plain sentence of description — no "Goal:" label, no blockquote, no metadata table. ## 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. Lead with the keywords a reader would search, **bold** the key terms. A few sentences, no more. +- `## 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: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. -- Every step carries one concrete example: a command with its useful output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- Every step carries one concrete example: a command with its real output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. - 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/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index 062d45f1..aad44ee3 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -2,7 +2,7 @@ # 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/refine-goal-checklist.md` first, and clear `assets/research-checklist.md` before drafting. +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 @@ -28,6 +28,7 @@ After curating, confirm every surviving candidate before presenting it. Spawn on - **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** — capture a usable example: copy a real output from the official docs, or run the command and capture what it prints. For an interactive command that cannot be scripted, mark the output for the human to paste. Never fabricate output. - Drop any candidate that cannot be confirmed against an official source. ## Reporting From 046797abb0f80e091633c2813b0afdbd3e1a34d2 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:06:02 +0200 Subject: [PATCH 12/23] docs(framework): use the real prompt-analytics dashboard image Replace the fabricated text output with the tool's official dashboard screenshot (cost by token type makes "cache reads dominate" visible). The slash-command placeholders now ask for a screenshot of the real output. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 0a988360..a725501b 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -28,7 +28,7 @@ $ /context file reads ████████ 19% CLAUDE.md ████ 9% system + tools ███████████ … -(illustrative — paste your real /context here) +(illustrative — replace with a screenshot of your real /context) ``` #### 2) 💸 Read the bill — `/cost` @@ -43,7 +43,7 @@ $ /context $ /cost Session: $0.42 · 1.2M tokens By: subagents 38% · MCP 21% · main 41% -(illustrative — paste your real /cost here) +(illustrative — replace with a screenshot of your real /cost) ``` #### 3) 🔍 Find your bad habits — `/insights` @@ -57,7 +57,7 @@ $ /cost $ /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 — paste your real /insights here) +(illustrative — replace with a screenshot of your real /insights) ``` #### 4) 📈 Track per-prompt with an analytics tool @@ -65,17 +65,10 @@ $ /insights Built-ins show one session; an analytics tool reads all your local logs and reveals where the bill truly sits. - Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). -- Run one against your local history — no setup, it parses `~/.claude`. +- Run it — `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` — no setup, it parses `~/.claude`. - The lesson it surfaces: **cache reads dwarf input + output**, so caching, not generation, is most of the bill. -```text -$ uvx --from prompt-analytics-for-claude-code prompt-analytics summary - Input tokens ~8M - Output tokens ~22M - Cache read tokens ~4.5B ← dominates the total - Source: live parse of ~/.claude/projects -(real run, token volumes rounded; cost figures omitted) -``` +![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 From 89033c0d580291217a856cef27ea17a56caba9a6 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:06:02 +0200 Subject: [PATCH 13/23] refactor(aidd-context): prefer images over text examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A real screenshot or GIF is unfakeable, faithful, and credible, where a text example can be approximated (the failure we hit). Make the contract and the research playbook prefer an image that matches the action — e.g. a tool's official screenshot — falling back to real text output only when no image exists. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../aidd-context/skills/12-cook/references/recipe-contract.md | 2 +- .../aidd-context/skills/12-cook/references/research-playbook.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index fb44bc84..988c8833 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -21,6 +21,6 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - One step = one action: never bundle several tools or commands under one heading; split them. - Each step is a `#### N) <emoji> Title` heading: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. - How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. -- Every step carries one concrete example: a command with its real output (show what it prints, not just the command), a config or snippet, a screenshot, or a short video/GIF link. +- 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 (show what it prints, not just the command), or a config or snippet. - 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/research-playbook.md b/plugins/aidd-context/skills/12-cook/references/research-playbook.md index aad44ee3..40db46c7 100644 --- a/plugins/aidd-context/skills/12-cook/references/research-playbook.md +++ b/plugins/aidd-context/skills/12-cook/references/research-playbook.md @@ -28,7 +28,7 @@ After curating, confirm every surviving candidate before presenting it. Spawn on - **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** — capture a usable example: copy a real output from the official docs, or run the command and capture what it prints. For an interactive command that cannot be scripted, mark the output for the human to paste. Never fabricate output. +- **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 From 4a7733a796608e9c4bc0ed7554a6cbd8919699a7 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:17:27 +0200 Subject: [PATCH 14/23] docs(framework): show real tool usage in token-optimization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - caveman: show its real `/caveman` invocation (and modes), not just a before/after. - RTK: a Mermaid diagram of the proxy flow + the real `rtk <command>` syntax (was a wrong `rtk proxy …`) and the README's own 200->10 token saving. - CLI vs MCP: a comparison table instead of prose. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index a725501b..0e5c753d 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -102,9 +102,11 @@ $ /compact keep the repro steps and the failing test; drop the file dumps Output is repetition you pay to generate, so cap the chatter. - Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). +- Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". - It forces short, filler-free replies (reported ~65% output cut, code intact). ```text +/caveman before: "Great question! Let me walk you through each step involved…" after: "3 steps:" ``` @@ -114,23 +116,29 @@ after: "3 steps:" Test, install, and build logs flood context with lines the model never needs. - Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). -- Run noisy commands through it; it keeps only the signal (reported 60–90%). - -```bash -$ rtk proxy npm test -# full build log in → only failures + final summary kept +- Prefix your command with it — `rtk git status`, `rtk cargo test` — it runs the command and returns only the signal. + +```mermaid +flowchart LR + A[your command] --> R[RTK proxy] + R --> C[real command runs] + C --> R + R -->|filter · group · truncate · dedupe| M[compact output to model] ``` +Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). + #### 9) 🔌 Prefer CLI over MCP -An MCP server loads its full schema every turn, while a CLI costs tokens only when called. +An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. -- Use the CLI when one exists (`gh`, `acli`, …); keep MCP for what has none. -- See [`mcp-installation.md`](mcp-installation.md). +| | CLI (`gh`, `acli`, …) | MCP server | +| --- | --- | --- | +| Token cost | a few, only when called | full tool schema, every turn | +| Context footprint | zero when idle | always present | +| Use when | a CLI exists | no CLI, or you need typed/live tool calls | -```bash -$ gh pr list # a few tokens per call, vs a GitHub MCP schema riding along every turn -``` +See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert From 1fc74fbb01144f7ac5e7511854f4db2c696fd720 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:17:28 +0200 Subject: [PATCH 15/23] refactor(aidd-context): add tool-example rules to recipe contract From the token-optimization review: - Show how to invoke a tool (its real command or slash invocation). - Reuse the canonical example from the tool's own site or README, never an invented one. - A "prefer X over Y" step uses a comparison table, not prose. - A structural or flow concept (proxy, pipeline, architecture) gets a small Mermaid diagram. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/references/recipe-contract.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 988c8833..68c40371 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -20,7 +20,10 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - 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: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. -- How-bullets are straight to the point and ordered for action. For a tool: where it is, then install it from its URL, then how to use it. +- How-bullets are straight to the point and ordered for action. 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`). - 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 (show what it prints, not just the command), or a config or snippet. +- Reuse the canonical example from the tool's own site or README, never an invented one. +- 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. - 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. From c3e79b990534ead23c8ebb25c1611be0dd7a6d64 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:20:56 +0200 Subject: [PATCH 16/23] docs(framework): use caveman's real before/after example Replace the invented caveman before/after with the verbatim example from its README (rule F: reuse the tool's own canonical example). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 0e5c753d..64ebe569 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -107,8 +107,10 @@ Output is repetition you pay to generate, so cap the chatter. ```text /caveman -before: "Great question! Let me walk you through each step involved…" -after: "3 steps:" + +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`. ``` #### 8) 🧹 Filter noisy command output From de9f8e32d7dfc9b98a574b36c922e51bdae18e03 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:28:21 +0200 Subject: [PATCH 17/23] docs(framework): numbered actions, valid-JSON config, tighter sections - Actions are numbered lists; descriptions are prose (no description-bullets). - settings.json shown as valid JSON, not a bash fragment. - RTK Mermaid uses concrete values (cargo test ~25k -> ~2.5k tokens). - CLI vs MCP notes MCP tool/context selection (cheaper, still slower). - Step 10 reworded plainly ("load knowledge on demand"). - Drop the weak Verify and the redundant Related; add a short conclusion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 100 ++++++++++++++++------------------ 1 file changed, 46 insertions(+), 54 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 64ebe569..753fc50c 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -18,16 +18,15 @@ Reach for this recipe when **cost** climbs faster than your output. `/context` paints your context as a grid, so you cut the biggest consumers instead of guessing. -- Run `/context` in Claude Code. -- Read the grid and find the heavy blocks: tool schemas, instruction files, long file reads. -- Attack the biggest block first. +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% - system + tools ███████████ … (illustrative — replace with a screenshot of your real /context) ``` @@ -35,9 +34,9 @@ $ /context `/cost` tells you what a session actually costs and where the spend goes. -- Run `/cost` (alias `/usage`). -- Read the breakdown by skill, subagent, and MCP server. -- Re-run it after a change to confirm the spend really dropped. +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 @@ -48,10 +47,10 @@ $ /cost #### 3) 🔍 Find your bad habits — `/insights` -`/insights` analyses how you prompt — which is probably sub-optimal — so you fix the pattern, not one prompt. +`/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. -- What you repeat every session → move it into the knowledge base (`CLAUDE.md`, rules). -- Counter-intuitive habits you never noticed → 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 @@ -62,11 +61,10 @@ $ /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. +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. -- Several exist: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) and [`ccusage`](https://www.npmjs.com/package/ccusage). -- Run it — `uvx --from prompt-analytics-for-claude-code prompt-analytics summary` — no setup, it parses `~/.claude`. -- 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) @@ -74,9 +72,9 @@ Built-ins show one session; an analytics tool reads all your local logs and reve Your instruction file ships every turn, so each cut line saves on every message. -- It lives at `CLAUDE.md` (or `.github/copilot-instructions.md`). -- Cut it to essentials and add explicit conciseness rules. -- Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. +1. Open `CLAUDE.md` (or `.github/copilot-instructions.md`). +2. Cut it to essentials and add explicit conciseness rules. +3. Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. ```md # CLAUDE.md @@ -88,8 +86,8 @@ Your instruction file ships every turn, so each cut line saves on every message. Compacting on your terms keeps what matters instead of letting auto-compaction guess. -- Watch context use and act around 60–70%. -- Run `/compact` with focus instructions naming what to keep. +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 @@ -99,11 +97,10 @@ $ /compact keep the repro steps and the failing test; drop the file dumps #### 7) 🗣️ Make the agent talk less -Output is repetition you pay to generate, so cap the chatter. +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. -- Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill (auto-detects 30+ agents). -- Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". -- It forces short, filler-free replies (reported ~65% output cut, code intact). +1. Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill. +2. Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". ```text /caveman @@ -117,50 +114,50 @@ after: New object ref each render. Inline object prop = new ref = re-render. Wr Test, install, and build logs flood context with lines the model never needs. -- Install a CLI proxy: [`RTK`](https://github.com/rtk-ai/rtk) (Rust) or [`SNIP`](https://github.com/edouard-claude/snip) (Go, YAML filters). -- Prefix your command with it — `rtk git status`, `rtk cargo test` — it runs the command and returns only the signal. +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[your command] --> R[RTK proxy] - R --> C[real command runs] - C --> R - R -->|filter · group · truncate · dedupe| M[compact output to model] + 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). #### 9) 🔌 Prefer CLI over MCP -An MCP server's schema rides along every turn; a CLI costs tokens only when you call it. +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 | full tool schema, every turn | -| Context footprint | zero when idle | always present | +| 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 -#### 10) 📚 Use progressive disclosure +#### 10) 📚 Load knowledge on demand -Load knowledge only when the task needs it, instead of riding along every turn. +Big procedural docs pasted into context are taxed every turn. Keep them as skills or rules instead: each loads only when its trigger matches the task, so it costs zero tokens until needed. -- Install an AIDD framework so skills, rules, and runbooks load on demand. +1. Install an AIDD framework so skills, rules, and runbooks load on demand. ```text -skill description matched → its steps load +skill trigger matches the task → its steps load no match → 0 tokens spent ``` #### 11) 🎯 Route by difficulty -The top model on routine work is wasted spend. +The top model on routine work is wasted spend, so match the model to the task. -- Send research and boilerplate to a cheaper model or a fresh subagent. -- Reserve the strongest model for hard reasoning. +1. Send research and boilerplate to a cheaper model or a fresh subagent. +2. Reserve the strongest model for hard reasoning. ```text research / boilerplate → small model or subagent @@ -171,22 +168,17 @@ architecture / tricky bug → top model Extended reasoning can silently add thousands of tokens on tasks that don't need it. -- Set `MAX_THINKING_TOKENS` to `0` for routine work. -- See the [Claude Code settings docs](https://code.claude.com/docs/en/settings). +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). -```bash -# settings.json (env) -"MAX_THINKING_TOKENS": "0" # disable extended thinking for routine work +```json +{ + "env": { + "MAX_THINKING_TOKENS": "0" + } +} ``` -## Verify +## In short -- Run `/cost` before and after a typical task — the token count drops measurably. -- `/context` shows your instruction file and tool schemas taking a smaller share of the window. -- A noisy command routed through RTK or SNIP returns far fewer lines than the raw run. - -## Related - -- [`mcp-installation.md`](mcp-installation.md) — why CLI beats MCP for context efficiency -- [Anthropic — Claude Code costs](https://code.claude.com/docs/en/costs) · [settings](https://code.claude.com/docs/en/settings) -- Tools: [`prompt-analytics-for-claude-code`](https://github.com/romainfjgaspard/prompt-analytics-for-claude-code) · [`ccusage`](https://www.npmjs.com/package/ccusage) · [`caveman`](https://github.com/JuliusBrussee/caveman) · [`RTK`](https://github.com/rtk-ai/rtk) · [`SNIP`](https://github.com/edouard-claude/snip) · [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) +Measure first, then stack the cheap wins — trimmed instructions, less chatter, filtered output — before reaching for model routing. Most of the bill is cache and repetition; cut those and the cost follows. From 33e8909ea23b71824ecdfc18d5c532933088aefb Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:28:22 +0200 Subject: [PATCH 18/23] refactor(aidd-context): add bullet/diagram/config/section rules to contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From the token-optimization review: - Actions are a numbered list; descriptions and indications are prose, never bullets. - A Mermaid diagram carries concrete example values. - A config example uses the file's real syntax (valid JSON for settings.json, valid YAML for frontmatter, ...). - Reuse a tool's canonical example captured verbatim — never a paraphrase or on the strength of a summary that one exists. - No `## Related` section (links live inline); `## Verify` is optional; recipes may end with a short conclusion. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/assets/recipe-template.md | 23 ++++++++----------- .../12-cook/references/recipe-contract.md | 12 ++++++---- 2 files changed, 16 insertions(+), 19 deletions(-) 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 a60cb11d..95a189c4 100644 --- a/plugins/aidd-context/skills/12-cook/assets/recipe-template.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipe-template.md @@ -12,11 +12,10 @@ #### 1) <emoji> <First step title> -<One benefit-focused line: what this gets the reader and why.> +<One benefit-focused line of what and why, in prose.> -- <where it is / what it is> -- <install it from its URL> -- <how to use it> +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> @@ -27,10 +26,10 @@ $ <command the reader runs> #### 2) <emoji> <Next step title> -<Benefit-focused what and why.> +<Benefit-focused what and why, in prose.> -- <how> -- <how> +1. <action> +2. <action> ```<lang> <a config or snippet the reader can copy> @@ -40,16 +39,12 @@ $ <command the reader runs> #### 3) <emoji> <Last step title — until the goal is reached> -<Benefit-focused what and why.> +<Benefit-focused what and why, in prose.> -- <how> +1. <action> ![<what this screenshot or video shows>](<path-or-url>) ## Verify -- <An observable check that proves it worked: a command, a UI state, a file that now exists.> - -## Related - -- <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/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 68c40371..849f9a2b 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -8,6 +8,7 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - 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 @@ -19,11 +20,12 @@ Rules for every `recipes/<kebab-slug>.md` the skill writes. - 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: it opens with an emoji, then one benefit-focused line of what and why. Number steps continuously. -- How-bullets are straight to the point and ordered for action. 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`). -- 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 (show what it prints, not just the command), or a config or snippet. -- Reuse the canonical example from the tool's own site or README, never an invented one. +- 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. +- 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. From 154af608c6f9d1bc623ea500685fc56d62d8a9ba Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Sat, 20 Jun 2026 18:32:34 +0200 Subject: [PATCH 19/23] docs(framework): expert steps use verified Claude Code config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Step 10 now audits which skills/tools run via `Ctrl+O` (toggles the detailed transcript), instead of the vaguer "load on demand". - Step 11 routes by difficulty with the real `model:` frontmatter field on a skill or agent (haiku/sonnet/opus/inherit) — example agent pinned to haiku. Both verified against the official Claude Code docs (interactive-mode, skills, sub-agents). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 753fc50c..747a90e2 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -141,29 +141,41 @@ See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert -#### 10) 📚 Load knowledge on demand +#### 10) 🔬 Audit which skills and tools run — `Ctrl+O` -Big procedural docs pasted into context are taxed every turn. Keep them as skills or rules instead: each loads only when its trigger matches the task, so it costs zero tokens until needed. +You optimise what you can see, so expand the transcript to watch what each turn actually invokes and pulls into context. -1. Install an AIDD framework so skills, rules, and runbooks load on demand. +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 -skill trigger matches the task → its steps load -no match → 0 tokens spent +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). + #### 11) 🎯 Route by difficulty -The top model on routine work is wasted spend, so match the model to the task. +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. Send research and boilerplate to a cheaper model or a fresh subagent. -2. Reserve the strongest model 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. -```text -research / boilerplate → small model or subagent -architecture / tricky bug → top model +```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). + #### 12) ✅ Cap extended thinking Extended reasoning can silently add thousands of tokens on tasks that don't need it. From 79dcb9f02e3c9174e005a426dac06b8dd9c25447 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 09:40:07 +0200 Subject: [PATCH 20/23] docs(framework): point the instruction-file step at AGENTS.md Use the framework's own concise AGENTS.md as the worked example for a trimmed instruction file, with its real rules (answer first, no narration), instead of a generic snippet. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- recipes/token-optimization.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 747a90e2..5aadad43 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -74,11 +74,12 @@ 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. Reuse the [`claude-token-efficient`](https://github.com/drona23/claude-token-efficient) ruleset. +3. Model it on a real concise instruction file: [AGENTS.md](../plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md). ```md -# CLAUDE.md -- Terse answers. No preamble, no "Let me…", no closing summary. +# 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. ``` From 90cf9fc4a102702c2337fa1342ba873e4efcbec5 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 09:40:07 +0200 Subject: [PATCH 21/23] refactor(aidd-context): apply analyses a recipe and asks before acting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A recipe is often a human tutorial, not an agent-runnable procedure. So apply now reads the recipe, classifies each step agent-doable vs human-only, and asks the user what to do before any change — then runs the chosen agent-doable steps and reports the human-only ones. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- .../skills/12-cook/actions/04-apply.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index b337eea5..fbc82a0b 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -1,6 +1,6 @@ # 04 - Apply recipe -Execute an existing recipe against the current project by spawning an agent that works through its steps as a tracked todo list, confirming with the user. +Analyse a chosen recipe, ask the user what to do, then run the agent-doable steps and report the rest. ## Input @@ -8,16 +8,17 @@ The recipe to apply, named by slug or topic. ## Output -The recipe's steps carried out on the project, tracked as a todo list, ending with its `## Verify` checks run and reported. +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. **Plan.** Turn each step under the recipe's steps heading (`## Steps to …`) into one todo entry. -3. **Confirm.** Show the user the plan and ask for confirmation before any change. -4. **Execute.** Spawn an agent via the `Task` tool to work the todo list in order. It marks each item done as it lands, and pauses for confirmation on any step that mutates the project. -5. **Verify.** Run the recipe's `## Verify` checks and report pass or fail. +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 produces a todo list mirroring the recipe's steps, asks for confirmation before executing, and runs the `## Verify` checks at the end. +- 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. From a918ef9429e7ad956cceb693478fa51707d9fc04 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 22 Jun 2026 10:08:32 +0200 Subject: [PATCH 22/23] docs(framework): add five verified token levers to the recipe MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit From a research pass, all verified against official Claude Code docs: - Plan mode (Shift+Tab ×2) — avoid execution-phase rework. - `/clear` between tasks — drop stale context instead of re-billing it. - Deny reads (`permissions.deny`) — keep vendor/dist/secrets out of context; the official answer to the unshipped `.claudeignore`. - Subagent offload — run high-volume ops in an isolated context. - Protect cache hits — avoid mid-task model/MCP/effort switches that invalidate the cache (closes the loop on "cache reads dominate"). Also fold the built-in `outputStyle: concise` into the "talk less" step. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --- plugins/aidd-context/CATALOG.md | 1 + .../skills/12-cook/actions/03-research.md | 6 +- recipes/token-optimization.md | 100 ++++++++++++++++-- 3 files changed, 94 insertions(+), 13 deletions(-) diff --git a/plugins/aidd-context/CATALOG.md b/plugins/aidd-context/CATALOG.md index 67166a74..55d19c4a 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -197,3 +197,4 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 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/skills/12-cook/actions/03-research.md b/plugins/aidd-context/skills/12-cook/actions/03-research.md index e6c8695b..24d2e27f 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -21,19 +21,19 @@ Every presented item is confirmed to exist, with its latest state and official l 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 +@../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 +@../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 +@../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. diff --git a/recipes/token-optimization.md b/recipes/token-optimization.md index 5aadad43..5f18d43f 100644 --- a/recipes/token-optimization.md +++ b/recipes/token-optimization.md @@ -83,7 +83,35 @@ Your instruction file ships every turn, so each cut line saves on every message. - Keep verbatim: code, quoted errors, security warnings. Cut the rest. ``` -#### 6) 🗜️ Compact deliberately +#### 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. @@ -96,12 +124,12 @@ $ /compact keep the repro steps and the failing test; drop the file dumps ### 🟡 Intermediate -#### 7) 🗣️ Make the agent talk less +#### 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. Install the [`caveman`](https://github.com/JuliusBrussee/caveman) skill. -2. Invoke it like any skill: `/caveman` (or `/caveman ultra` for the hardest cut); stop with "normal mode". +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 @@ -111,7 +139,9 @@ before: The reason your React component is re-rendering is likely because you're after: New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`. ``` -#### 8) 🧹 Filter noisy command output +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. @@ -128,7 +158,24 @@ flowchart LR Real saving: `git push` (15 lines, ~200 tokens) -> `rtk git push` (1 line, ~10 tokens). -#### 9) 🔌 Prefer CLI over MCP +#### 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. @@ -142,7 +189,7 @@ See [`mcp-installation.md`](mcp-installation.md). ### 🔴 Expert -#### 10) 🔬 Audit which skills and tools run — `Ctrl+O` +#### 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. @@ -158,7 +205,7 @@ Ctrl+O — transcript expanded See the [keyboard shortcuts](https://code.claude.com/docs/en/interactive-mode). -#### 11) 🎯 Route by difficulty +#### 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. @@ -177,7 +224,40 @@ 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). -#### 12) ✅ Cap extended thinking +#### 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. @@ -194,4 +274,4 @@ Extended reasoning can silently add thousands of tokens on tasks that don't need ## In short -Measure first, then stack the cheap wins — trimmed instructions, less chatter, filtered output — before reaching for model routing. Most of the bill is cache and repetition; cut those and the cost follows. +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. From c5279bd3c8194201534749f0233ed40e574346a9 Mon Sep 17 00:00:00 2001 From: alexsoyes <contact.alexsoyes@gmail.com> Date: Mon, 6 Jul 2026 18:53:20 +0200 Subject: [PATCH 23/23] feat(aidd-context): bundle cook recipes in skill --- README.md | 4 +- aidd_docs/CONTRIBUTING.md | 4 + aidd_docs/README.md | 2 + aidd_docs/recipes/.gitkeep | 1 + docs/CATALOG.md | 2 +- plugins/aidd-context/CATALOG.md | 1 + plugins/aidd-context/README.md | 2 +- .../actions/02-scaffold-docs.md | 9 ++- .../02-project-memory/assets/CONTRIBUTING.md | 4 + .../skills/02-project-memory/assets/README.md | 1 + plugins/aidd-context/skills/12-cook/SKILL.md | 6 +- .../skills/12-cook/actions/01-list.md | 29 ++++--- .../skills/12-cook/actions/02-upsert.md | 22 +++--- .../skills/12-cook/actions/03-research.md | 6 +- .../skills/12-cook/actions/04-apply.md | 5 +- .../assets/recipes/mcp-installation.md | 60 ++++++++++++++ .../12-cook/assets/recipes/ship-a-feature.md | 79 +++++++++++++++++++ .../12-cook/assets/recipes/start-a-project.md | 67 ++++++++++++++++ .../assets/recipes}/token-optimization.md | 2 +- .../12-cook/references/recipe-contract.md | 5 +- .../12-cook/references/recipe-locations.md | 27 +++++++ recipes/README.md | 16 ---- recipes/mcp-installation.md | 53 ------------- recipes/ship-a-feature.md | 37 --------- recipes/start-a-project.md | 34 -------- 25 files changed, 301 insertions(+), 177 deletions(-) create mode 100644 aidd_docs/recipes/.gitkeep create mode 100644 plugins/aidd-context/skills/12-cook/assets/recipes/mcp-installation.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/recipes/ship-a-feature.md create mode 100644 plugins/aidd-context/skills/12-cook/assets/recipes/start-a-project.md rename {recipes => plugins/aidd-context/skills/12-cook/assets/recipes}/token-optimization.md (98%) create mode 100644 plugins/aidd-context/skills/12-cook/references/recipe-locations.md delete mode 100644 recipes/README.md delete mode 100644 recipes/mcp-installation.md delete mode 100644 recipes/ship-a-feature.md delete mode 100644 recipes/start-a-project.md 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: `<plugin>:<NN>-<slug>`. 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 55d19c4a..5ed76aa5 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -195,6 +195,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `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 - <A naming or placement rule specific to this repo> 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 035b55eb..eacd5eca 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -6,7 +6,7 @@ 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 @@ -17,13 +17,15 @@ Maintains the project's `recipes/` how-to sheets, the short runbooks that live a | 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, `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. +Run `list` to survey project and bundled recipes, `research` to gather insights, `upsert` to author one, `apply` to run an existing one against the project. Always run `research` before authoring or substantially updating a recipe — never draft from memory alone. Run `list` first when the user names no recipe. Before running an action, read its file in `actions/`, not only the table or assets. ## References +- `references/recipe-locations.md`: where project and bundled recipes live, how resolution works, and when writes target each home. - `references/recipe-contract.md`: the rules every recipe file follows; `upsert` writes to it. ## Assets - `assets/recipe-template.md`: the canonical recipe scaffold `upsert` renders from, and the shape `list` parses. +- `assets/recipes/`: bundled recipes shipped with this skill. 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 561fd1e2..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 | Description | -| --- | --- | -| [<title>](recipes/<file>) | <description> | +| # | 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 and the one-sentence description right below it. -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 and description. -- 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 e7b6f360..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,8 +1,9 @@ # 02 - Upsert recipe -Create or update one recipe at `recipes/<slug>.md`, scaffolded from the recipe template and following the recipe contract: +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 ``` @@ -13,19 +14,22 @@ The recipe topic. Ask for any missing field (description, steps, verify, related ## 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. **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. +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 - 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. -- `recipes/README.md` carries a row for `<slug>`: its title linked, plus the one-sentence description. -- A new recipe that highly overlaps an existing one triggers an update-or-create prompt before scaffolding. +- `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 index 24d2e27f..3514b6e5 100644 --- a/plugins/aidd-context/skills/12-cook/actions/03-research.md +++ b/plugins/aidd-context/skills/12-cook/actions/03-research.md @@ -4,7 +4,7 @@ Refine the target recipe with a checklist, scout for the highest-value insights, ## Input -The recipe or topic to modernize. If a recipe, its `recipes/<slug>.md` holds the current approach and coverage. +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 @@ -14,11 +14,11 @@ Three parts, then a recommendation: 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/`. +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. Read `recipes/<slug>.md` first when the recipe exists. Run `list` when it is unnamed. +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 diff --git a/plugins/aidd-context/skills/12-cook/actions/04-apply.md b/plugins/aidd-context/skills/12-cook/actions/04-apply.md index fbc82a0b..212bacdf 100644 --- a/plugins/aidd-context/skills/12-cook/actions/04-apply.md +++ b/plugins/aidd-context/skills/12-cook/actions/04-apply.md @@ -4,7 +4,7 @@ Analyse a chosen recipe, ask the user what to do, then run the agent-doable step ## Input -The recipe to apply, named by slug or topic. +The recipe to apply, named by number from the latest `list`, slug, title, or topic. ## Output @@ -12,7 +12,7 @@ A short analysis of the recipe — what it achieves, and which steps the agent c ## Process -1. **Locate.** Resolve the recipe to `recipes/<slug>.md` and read it. Run `list` first when the recipe is unnamed. +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. @@ -21,4 +21,5 @@ A short analysis of the recipe — what it achieves, and which steps the agent c ## 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/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/recipes/token-optimization.md b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md similarity index 98% rename from recipes/token-optimization.md rename to plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md index 5f18d43f..67c096fa 100644 --- a/recipes/token-optimization.md +++ b/plugins/aidd-context/skills/12-cook/assets/recipes/token-optimization.md @@ -74,7 +74,7 @@ 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](../plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md). +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) diff --git a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md index 849f9a2b..f06f1bf0 100644 --- a/plugins/aidd-context/skills/12-cook/references/recipe-contract.md +++ b/plugins/aidd-context/skills/12-cook/references/recipe-contract.md @@ -2,11 +2,12 @@ # Recipe contract -Rules for every `recipes/<kebab-slug>.md` the skill writes. +Rules for every recipe file the skill writes. ## File -- Path: `recipes/<kebab-slug>.md`. +- 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. 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/recipes/README.md b/recipes/README.md deleted file mode 100644 index b79bbf4d..00000000 --- a/recipes/README.md +++ /dev/null @@ -1,16 +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 | -| [Token optimization for AI IDEs](token-optimization.md) | Cut token usage and cost in AI coding assistants without losing output quality | Intermediate | - -> More coming — 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.