grokkit/docs/user-guide/recipe.md

👨‍🍳 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.

# 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

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