feat(aidd-context): refresh cook recipes and enforce heading hierarchy by alexsoyes · Pull Request #521 · ai-driven-dev/framework

alexsoyes · 2026-07-26T15:02:37Z

Summary

enforce continuous heading nesting in the cook template, contract, and upsert action
refresh the AIDDy, MCP installation, and token optimization recipes
keep client-specific commands explicit while preserving RTK/SNIP, MCP Tool Search, model routing, and prompt-cache guidance
remove the duplicated baseline/context measurement in the token recipe

Validation

node scripts/check-markdown-links.js — 0 broken links in 537 files
heading hierarchy — 3/3 in-scope bundled recipes
token optimization levers — 6/6 preserved
git diff --check
pre-commit Markdown and commitlint hooks

CLI tests were not run because the PR changes no cli/** files and the gitignored CLI dependencies are intentionally absent.

Keep recipe steps actionable, enforce valid heading nesting, and preserve verified token and MCP guidance.

Separate durable agent instructions from scoped rules and keep each optimization technique directly actionable.

Keep bundled guidance concise, reproducible, and mechanically verifiable.

Keep lint settings compatible with the installed Biome schema.

alexsoyes · 2026-08-24T06:32:04Z

@blafourcade t'es good dessus ?

blafourcade · 2026-08-24T08:14:38Z

 ## Input

-The recipe topic. Ask for any missing field (description, steps, verify, related) before writing.
+The recipe topic. Infer description, steps, and verification from the request and research; ask only for a missing decision that changes the recipe's outcome or scope.


Je pense que le Ask devrait être dans un step plutôt que l'Input ?

blafourcade · 2026-08-24T08:17:11Z

@@ -1,12 +1,12 @@
-<!-- Read before spawning research agents in 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. -->
+<!-- Read during 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. -->


Besoin de remettre during 03 si on le nomme dans cette step uniquement ?

blafourcade · 2026-08-24T08:18:29Z

@@ -9,24 +9,41 @@ Rules for every recipe file the skill writes.
 - 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`.


C'est spécific au framework ici, est-ce qu'on veut ce cas précis dans un skill d'un framework commun ?

blafourcade · 2026-08-24T08:20:16Z

+
+Check one recipe or every available recipe without changing files.
+
+```text


Pourquoi on a ça ici dans le skill lui même ? Ca serait à la limite dans le SKILL.md et encore

blafourcade · 2026-08-24T08:21:04Z

+```
+
+```md
+@../references/recipe-locations.md


On ne permet pas dans les règles du skill-generate les references comme ça au niveau du titre mais dans les step associées. J'ai bien vérifié et regénéré avec le skill il ne propose jamais ça de mon côté

blafourcade · 2026-08-24T08:22:27Z

+## Process
+
+1. **Resolve.** Resolve one recipe with `@../references/recipe-locations.md`, or keep `all` as the full project-plus-bundled scope.
+2. **Check structure.** Run `node <skill-directory>/scripts/validate-recipe.mjs <resolved-path>` or `node <skill-directory>/scripts/validate-recipe.mjs --all`. Preserve its exit code and findings.


Je pense qu'on peut simplifier en disant run the script with appropriate input (all, etc)

blafourcade · 2026-08-24T08:24:18Z

+
+## Validation
+
+- Run `actions/05-validate.md` after `upsert`, deterministic pass first and semantic pass second; fix and rerun until both pass.


Pourquoi a t on des appels d'actions dans les references ?

blafourcade · 2026-08-24T08:24:52Z


 # Cook

 Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bundled recipes ship inside this skill under `assets/recipes/`.


Peux-tu appeler skill-generate pour changer le foramt de ce fichier avec le mermaid chart désormais ?

blafourcade · 2026-08-24T08:25:37Z

-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.
+Validation entry points: `cook validate <recipe>` and `cook validate all`.
+
+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, and `validate` to check one or all recipes without changing them. Always run `research` before authoring or substantially updating a recipe — never draft from memory alone. Run `list` first when the user names no recipe.


Avec le nouveau format et le mermaid chart tu auras normalement pas besoin d'expliciter autant de chose

blafourcade · 2026-08-24T08:27:58Z

 - 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.
+- Sections: the description, then the steps. `## Verify` is optional only when no useful observable check exists. End with at most one short conclusion. Never add a `## Related` section: links live inline where they are used.


L'assets n'est pas assez descriptive pour qu'il remplisse correctement ? Tu es obligé d'indiquer autant de détail pour tout remplir ? (peut être, je challenge si pas de AI Slop)

alexsoyes mentioned this pull request Jul 26, 2026

Clarify recipe step heading hierarchy #519

Closed

alexsoyes marked this pull request as ready for review August 7, 2026 06:41

alexsoyes requested a review from a team as a code owner August 7, 2026 06:41

alexsoyes enabled auto-merge (squash) August 7, 2026 07:03

alexsoyes requested a review from blafourcade August 16, 2026 01:56

alexsoyes added 4 commits August 24, 2026 14:26

docs(aidd-context): refresh cook recipes

e4d814a

Keep recipe steps actionable, enforce valid heading nesting, and preserve verified token and MCP guidance.

docs(aidd-context): streamline token optimization recipe

36f48da

Separate durable agent instructions from scoped rules and keep each optimization technique directly actionable.

feat(aidd-context): validate technical recipes

6e45f17

Keep bundled guidance concise, reproducible, and mechanically verifiable.

chore(cli): migrate Biome configuration

09f2d32

Keep lint settings compatible with the installed Biome schema.

alexsoyes force-pushed the codex/recipes-clean branch from 19c032e to 09f2d32 Compare August 24, 2026 06:30

blafourcade reviewed Aug 24, 2026

View reviewed changes

blafourcade assigned alexsoyes Aug 24, 2026

blafourcade changed the title ~~Refresh cook recipes and enforce heading hierarchy~~ feat(aidd-context): refresh cook recipes and enforce heading hierarchy Aug 24, 2026

Navigation Menu

Uh oh!

feat(aidd-context): refresh cook recipes and enforce heading hierarchy - #521

feat(aidd-context): refresh cook recipes and enforce heading hierarchy#521
alexsoyes wants to merge 4 commits into
nextfrom
codex/recipes-clean

alexsoyes commented Jul 26, 2026

Uh oh!

alexsoyes commented Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

blafourcade Aug 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -1,12 +1,12 @@
		<!-- Read before spawning research agents in 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. -->
		<!-- Read during 03-research. The scouting angles, the bar each candidate must clear, and how to verify them. Not a recipe itself. -->

		@@ -9,24 +9,41 @@ Rules for every recipe file the skill writes.
		- 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`.


		Check one recipe or every available recipe without changing files.

		```text


		## Validation

		- Run `actions/05-validate.md` after `upsert`, deterministic pass first and semantic pass second; fix and rerun until both pass.


		# Cook

		Maintains recipe how-to sheets. Project recipes live in `aidd_docs/recipes/`; bundled recipes ship inside this skill under `assets/recipes/`.

Uh oh!

Conversation

alexsoyes commented Jul 26, 2026

Summary

Validation

Uh oh!

alexsoyes commented Aug 24, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants