# Dev Guidance for Recipe Tool (Executor & Creator)

This document provides guidance for developers working on the Recipe Tool project. It includes information on the currently evolving project's structure, thinking behind the design, and how to navigate for now. It is a work in progress and will be updated with just the most important bits of information as the project evolves.

These are the early days of using LLMs for assistance in software development in this particular way and it has a lot of benefits and also introduces some new challenges. The goal of this project is to help us accelerate our own work as much as possible while also encoding our learnings back into automations that we can re-use for further acceleration and to share the knowledge and automations with others. This is a new way of working and we are all learning together.

Please do not open issues for this project. There are so many things that do not work as we want yet and we are well aware of and won't have time to even go after all of them. If you find value in the current state, great! If you don't, thanks for checking it out and feel free to check back in later.

Due to the expectation of frequent breaking changes, we encourage you to fork the project, work with something that works for you, hack on it, experiment with it, share your learnings, and help us all learn together. We are all learning together and we appreciate your understanding and support as we figure this out. Don't be quick to bring in the latest changes from upstream until you are ready to do so - and when you do, try passing the updated `ai_context/generated` files + your recipes/specs/docs to your assistant/LLM and see if it can help you with the changes. If it can't, then you can always revert back to your forked version. This is a new way of working and we are all learning together.

## Contributing to the Project

**MOST CONTRIBUTIONS TO THIS PROJECT _WILL_ BE REJECTED**

This is a very opinionated approach to generating code and files for this project. It is easy enough to take the work here and have an assistant/LLM help you customize or extend it to meet your needs that we believe it may eventually become something even simpler and more easily personalized. In the meantime, there is a path being explored that requires running fast and focusing and trying to figure out how to be more collaborative in a single repo are challenges that we'll circle back to later.

In the meantime, if you believe you have a really valuable contribution that is low cost to review and see impact of, we encourage you to share it as a PR but please understand that a) we may not even have time to look at it, b) if we do and we like it, we'll likely take the idea and not the work as-is (there is a learning we're having around limiting any contradictions to what we want presented to assistants/LLMs we share this full codebase with to take understanding from in order to assist us better). But please don't take it personally if your contributions are rejected. We are trying to keep the project as simple and focused as possible. Once we get past the initial thrashing of the project, we hope to focus on solving some of the new collaboration challenges that are arising from this new way of working. We are all learning together and we appreciate your understanding and support as we figure this out.

## Project Structure

The project is organized into several key directories, each serving a specific purpose. Here's a brief overview of the main directories:

- `ai_context`: Contains files intended to be shared with LLMs. These files provide context and information about the project, its components, and usage examples. This also includes both generated files (in `generated`) and any static files that may get referenced in the core recipes provided in this project.

- `ai_context/generated` & `ai_context/git_collector`: Contain files generated by the `make ai-context-files` script. These files provide a convenient roll-up of parts of this project to serve as context for sharing with other assistants/LLMs. Rebuild these files whenever you make significant changes to the project recipes, specs, and/or docs so that the version avaialble to download from the repo is up-to-date. (Future task: automate this as a git-hook?)

- `docs`: Contains _very limited_ documentation files, including this one. The documentation is currently sparse and will likely remain so. In this new way of working, the specs + docs + recipes + code + included files all provide more than enough rich context to let any reasonably capable assistant/LLM understand and help us with whatever we need. Documentation is hard to keep up to date (though we'll likely work on automating that as part of this work) and the impact of conflicting / outdated documentation is much more severe than the impact of having no documentation at all in this context (sharing with LLMs for assistance). So, for now, we are keeping this to a minimum. Please try to limit _must share_ info for _users_ of the project to the root `README.md` file.

- `recipe_executor`: Contains the core components of the Recipe Executor. This includes the main logic for executing recipes, handling LLM calls, and managing file generation. The components are organized into subdirectories based on their functionality. The code is all, 100% throw-away as it is all 100% generated by the tool itself and will continue to be so. It is only checked in so that we have it as a tool to execute to generate the next version of the code (wild, eh?). Any desired changes to the tool should be made via the recipes in the `recipes/recipe_executor` directory, use the tool itself to generate new code into an `output` directory (or right into the `recipe_executor` directory if you like living on the edge and are comfortable using git to revert any changes you don't like), copy individual files/all to the running code directory to try it out (until we build recipes for testing). Once satisfied with changes, run the `build_ai_context_files.py` script to generate updated `ai_context/generated` files. Check in the recipe changes _and_ the generated code _and_ the generated ai_context files. This will ensure that everyone else can download the latest built versions right from the repo and use them in their current state.

- `recipes`: Contains the recipes used to generate the code and files in the project. The recipes are organized into subdirectories based on their functionality. Each recipe is designed to be modular and reusable, allowing for easy customization and extension. Technically, the main `recipes_extractor` directory is portable and can be used in any other project/location outside of this repo and _all_ recipes are optional, but serve as examples for how to use the tool.

- `recipes/recipe_executor`: Contains the recipes used to generate the code and files in the `recipe_executor` directory. These recipes are designed to be modular and reusable, allowing for easy customization and extension. The recipes are organized into subdirectories based on their functionality. This is the minimal set of recipes to be able to generate the tool itself.

- `recipes/recipe_creator`: Contains the recipes used to generate new recipes based on a recipe idea.
