Recipe Specification v0.1
The recipe is Codewright's core data model. One YAML definition generates the website page, API response, MCP tool behavior, and agent-skill step.
File location & naming
recipes/<category>/<slug>.yaml — e.g. recipes/git/undo-last-commit.yaml. Recipe id is <category>.<slug_with_underscores> — e.g. git.undo_last_commit. Categories (MVP): git, docker, files, network, node, db.
Schema
id: git.undo_last_commit # required, unique, stable forever
version: 1 # required, integer; bump on breaking change
title: Undo the last commit # required, imperative, <= 60 chars
description: > # required, plain English, what & why
Removes the last commit from the current branch while keeping the
changes staged, so you can amend and re-commit.
category: git # required, one of the six categories
tags: [git, commit, undo] # required, lowercase kebab/plain words
risk: medium # required: read_only | low | medium | destructive
requires_confirmation: false # required; MUST be true when risk = destructive
parameters: # optional
- name: keep_changes
type: boolean # string | number | boolean | enum
default: true
description: Keep the commit's changes staged in the working tree.
platforms: # required, >= 1 of: macos, linux, windows
macos:
steps:
- run: git reset --soft HEAD~1 # {{param}} substitution allowed
purpose: Remove the commit, keep changes staged
risk: medium # per-step override, optional
linux:
same_as: macos # dedupe identical platforms
verification: # required: how to confirm success
- run: git status
expect: Changes staged, previous commit gone from `git log`.
undo: # required: one of the two forms
possible: true
steps:
- run: git reset 'HEAD@{1}'
purpose: Restore the branch to before the reset
pitfalls: # optional but encouraged
- Does not work if there is no previous commit (fresh repo).
related: [git.amend_commit, git.revert_commit] # optional recipe ids
Risk levels
| Level | Meaning | Examples |
|---|---|---|
| Read-only | Inspects state without changing anything. | git status, lsof -i :3000, docker system df |
| Low risk | Reversible with a routine follow-up command. | create branch, git stash, generate SSH key |
| Medium risk | Changes state; undo path documented. | git reset --soft, kill process, run migration |
| Destructive | Deletes or overwrites; confirmation required. | docker system prune --volumes, rm -rf, force push |
Rules
destructive ⇒ requires_confirmation: true and an undo block (possible: false with a note is acceptable). Prefer recipes structured inspect → act → verify. Never include commands that exfiltrate data, disable security controls, or require credentials inline.Agent-readable rendering
POST /api/v1/recipes/{id}/render with {platform, params} returns:
{
"id": "git.undo_last_commit",
"version": 1,
"risk": "medium",
"requires_confirmation": false,
"commands": [
{ "command": "git reset --soft HEAD~1", "purpose": "...", "risk": "medium" }
],
"verification": [{ "command": "git status", "expect": "..." }],
"undo": { "possible": true, "commands": ["git reset 'HEAD@{1}'"] }
}
Validation (CI-enforced)
Every PR touching recipes/ must pass pnpm recipes:validate, which checks: schema conformance, unique ids, id↔path consistency, parameter references ({{...}}) resolve, risk/confirmation rules, and that all related ids exist. String parameters may declare pattern and pattern_description together — patterns must be anchored with ^ and $ and match any declared default. same_as must reference another configured platform that contains steps; self-references and chains of same_as aliases are invalid.