feat(aidd-context): refresh cook recipes and validate practical guides by alexsoyes · Pull Request #521 · ai-driven-dev/framework

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

Summary

Restore the original English Markdown recipe scaffold, with optional Why, Verify, and difficulty sections.
Reduce the recipe contract to concise, non-duplicated principles and address the review comments on routing, references, and report assets.
Keep structural validation read-only and adaptable; fix file-read failures, symlinked entry points, and punctuation false positives.
Refresh the AIDDy, MCP, and token recipes; retire the two bundled project/feature flow guides. Correct the current RTK Codex hook guidance.

Validation

Independent review: cleanup and six-file Cook template follow-up approved, no remaining findings; all 19 supplied template criteria satisfied and 27 validator tests passed.
Global pre-commit: 576 script tests and 140 CLI architecture tests passed; manifests, typecheck, lint, paths, and Markdown links passed.
Pre-push: Knip passed; 6,795 CLI tests passed, one optional local Kilo-runtime test skipped.
JSON, YAML, TOML, and shell examples parsed successfully.
Fresh Codex flat and Claude marketplace distributions each returned the exact three-recipe validation PASS output.
Commit and push hooks ran without bypass. The latest commit is 476678cd.

The cleanup review and evidence are recorded in aidd_docs/tasks/2026_10/2026_10_01_cook-pr-cleanup/review.md. Remote CI, including Windows and CodeQL, passed on 476678cd; no open CodeQL alerts remain for this PR. Interactive client workflows were not executed.

Cook template conformance

The follow-up changes only the router and five actions, preserving their existing behavior. The recipe template, contract, recipes, references, and validator are unchanged by this follow-up. Paths below are relative to plugins/aidd-context/skills/12-cook/.

File	Checked and corrected	Remaining findings
`SKILL.md`	Routing entries, handoffs, outcomes, repair loops, and the single shared index rule	None
`actions/01-list.md`	Ordered process, recipe listing guarantees, and observable Case / Pass tests	None
`actions/02-upsert.md`	Research evidence, new-only deduplication, bundled authorization, preservation, and repair reuse	None
`actions/03-research.md`	One-sentence process steps, source verification, complete outputs, and Case / Pass tests	None
`actions/04-apply.md`	Analysis before choice, per-file confirmation, human-only steps, and Case / Pass tests	None
`actions/05-validate.md`	Purpose sentence, section ownership, read-only checks, and optional parser disclosure	None

A read-only independent checker reviewed all six complete files and their cited Cook contracts. Fresh Codex flat and Claude marketplace builds contain the six current files and return the exact three-recipe validator PASS output.

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

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)

Keep the cook router, actions, and recipe contract consistent with the skill-generation rules and Baptiste's review feedback.

Keep the original Markdown scaffold adaptable and let validation reject broken recipes without imposing editorial heuristics. Make file reads and symlinked entry points reliable.

Accept native Windows line endings and derive heading anchors without regex-based tag stripping. Keep the symlink entry-point regression active across hosts.

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

alexsoyes added 2 commits August 27, 2026 15:00

chore: merge next into codex/recipes-clean

97b6abb

fix(aidd-context): align cook skill with generated format

4a9f80b

Keep the cook router, actions, and recipe contract consistent with the skill-generation rules and Baptiste's review feedback.

waewoo mentioned this pull request Sep 28, 2026

docs(framework): make intent-based skill workflows discoverable #931

Open

7 tasks

alexsoyes added 2 commits October 1, 2026 06:22

fix(aidd-context): preserve standalone cook workflows

ef53196

chore(vcs): merge next and verify cook integration

ff28a45

github-advanced-security Bot found potential problems Sep 30, 2026

View reviewed changes

fix(aidd-context): restore readable recipe authoring

74d1c18

Keep the original Markdown scaffold adaptable and let validation reject broken recipes without imposing editorial heuristics. Make file reads and symlinked entry points reliable.

alexsoyes changed the title ~~feat(aidd-context): refresh cook recipes and enforce heading hierarchy~~ feat(aidd-context): refresh cook recipes and validate practical guides Oct 1, 2026

github-advanced-security Bot found potential problems Oct 1, 2026

View reviewed changes

Comment thread plugins/aidd-context/skills/12-cook/scripts/validate-recipe.mjs Fixed

alexsoyes added 2 commits October 1, 2026 10:26

fix(aidd-context): make recipe checks portable

ab2f64d

Accept native Windows line endings and derive heading anchors without regex-based tag stripping. Keep the symlink entry-point regression active across hosts.

fix(aidd-context): align cook with skill templates

476678c

Navigation Menu

feat(aidd-context): refresh cook recipes and validate practical guides - #521

feat(aidd-context): refresh cook recipes and validate practical guides#521
alexsoyes wants to merge 11 commits into
nextfrom
codex/recipes-clean

alexsoyes commented Jul 26, 2026 •

edited

Loading

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 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.

Conversation

alexsoyes commented Jul 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Cook template conformance

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

alexsoyes commented Jul 26, 2026 •

edited

Loading