# 👨‍🍳 Recipe Guide

The `recipe` command is the most powerful feature in Grokkit. It lets you define sophisticated, multi-step, transactional workflows that Grok executes step-by-step with full transparency and user approval.

### What is a Recipe?

A recipe is a plain markdown file (`.md`) that lives in:
- `.grokkit/recipes/` (project-local, preferred)
- `~/.local/share/grokkit/recipes/` (global)

Each recipe contains:
- YAML frontmatter (metadata + parameters)
- Clear, numbered steps written in natural language
- Optional final summary

### Usage

Execute transactional "recipes" for complex, multi-step AI workflows.

```bash
# Run a project-local recipe
grokkit recipe run result-refactor

# Pass parameters to the recipe
grokkit recipe run result-refactor -p package_path=internal/git -p dry_run=false

# Run a specific recipe file
grokkit recipe run ./my-custom-recipe.md
```

### Recipe System

- **Local Recipes**: Stored in `.grokkit/recipes/*.md`.
- **Global Recipes**: Stored in `~/.local/share/grokkit/recipes/*.md`.
- Recipes are **markdown-based** with YAML frontmatter for parameters and configuration.

### Anatomy of a Recipe

```markdown
---
name: result-refactor
description: Convert naked errors to Result[T] pattern
version: 1.0

parameters:
  package_path:
    type: string
    default: internal
    description: Package to refactor

project_languages:
  - go

extensions:
  go:
    - .go

search_pattern: "if err != nil"

allowed_shell_commands:
  - go test
  - go vet
---

# Result[T] Refactoring

**Overview**
Converts traditional Go error handling to the modern Result[T] monadic style.

## Execution Steps

### Step 1: Discover files
**Objective:** Find files that need refactoring.  
**Instructions:** Recursively scan `{{.package_path}}`...  
**Expected output:** Clean list of full file paths.

### Step 2: Read-Only Shell: Explore project structure
**Objective:** Get additional context if needed.  
**Instructions:** Use safe read-only commands...

### Step 3: Refactor each file
...

### Step 4: Apply or patch
...
```

### Key Features

* Parameters — override with --param key=value
* Read-only shell access — use steps titled "Read-Only Shell..." for safe ls, cat, tree, find, rg, jq, etc.
* User confirmation — you approve every shell command
* Dry-run safety — most recipes support dry_run=true by default
* Transactional — you see every step and can stop at any time

### Best Practices

* Keep recipes focused (one clear goal)
* Use "Read-Only Shell" steps when the LLM needs context
* Always include a good search_pattern for discovery
* Document expected output clearly in each step