Greg Gauthier
cd47686679
- Simplified README.md by moving detailed command docs, workflows, and development info to dedicated user-guide/ and developer-guide/ directories. - Created index.md files for both guides to improve navigation. - Extracted individual command guides (e.g., chat.md, edit.md) into user-guide/ for focused, maintainable documentation. - Moved architecture, configuration, and troubleshooting to developer-guide/. - Updated README links to point to the new docs structure.
103 lines
2.6 KiB
Markdown
103 lines
2.6 KiB
Markdown
# 👨🍳 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
|
|
|