Greg Gauthier ec692b2086 docs(recipe): add feature overview for recipe system

Introduces a new Markdown file in todo/doing that outlines the recipe feature implementation, including key components, parsing logic, CLI integration, and progress checklist.

2026-03-06 19:16:57 +00:00

2.2 KiB

Raw Permalink Blame History

Recipe Feature Overview

The feature/recipe_implementation branch introduces a "Recipe" system to grokkit. This system allows for complex, multi-step refactorings or tasks to be defined in Markdown files and executed sequentially by an LLM.

Key Components

1. Recipe Definitions

Recipes are stored as Markdown files (e.g., .grokkit/recipes/result-refactor.md) with:

YAML Frontmatter: Metadata like name, description, version, and parameters.
Structured Steps: Defined using ### Step N: Title headings.
Step Details: Each step includes **Objective:**, **Instructions:**, and **Expected output:** sections.

2. Internal Recipe Package (`internal/recipe/`)

types.go: Defines the data structures for Recipe, Step, and Parameter.
loader.go:
- Parses Markdown files and extracts YAML frontmatter.
- Uses regular expressions (stepRe, subRe) to extract step details.
- Supports basic text/template rendering for parameter substitution in instructions.
runner.go:
- Orchestrates recipe execution.
- Currently implements a dry-run/preview mode that prints steps to the console.
- Placeholder for future LLM integration.

3. CLI Integration (`cmd/recipe.go`)

grokkit recipe run [recipe-name|recipe.md]: The main entry point for users.
Path Resolution:
1. Explicit Path: Checks if the argument is a direct file path.
2. Project Local: Looks in .grokkit/recipes/ within the project root.
3. Global Share: Falls back to ~/.local/share/grokkit/recipes/ (XDG-compliant).

Technical Details

Go Version: 1.24.2.
Dependencies: gopkg.in/yaml.v3 for frontmatter, github.com/spf13/cobra for CLI.
Parsing: Uses multi-line regex for robust section extraction even with varied Markdown formatting.

Current Progress & Next Steps

Recipe data structures and YAML frontmatter parsing.
Markdown step extraction and template rendering.
CLI command with project-local/global path resolution.
Integration with LLM for actual step execution.
Support for --param flags in the CLI.
Shell command execution within steps (if allowed).

2.2 KiB Raw Permalink Blame History