You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Launch claude with --dangerously-skip-permissions for uninterrupted setup
- Rewrite skill to accept plain-English descriptions instead of asking about internals
- Add user arguments knowledge to the skill
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: docs/changelog.md
+10Lines changed: 10 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,16 @@ description: Ralphify release history — new features, bug fixes, and breaking
6
6
7
7
All notable changes to ralphify are documented here.
8
8
9
+
## 0.1.11 — 2026-03-18
10
+
11
+
### Improved
12
+
13
+
-**`ralph new` runs without permission prompts** — Claude Code is now launched with `--dangerously-skip-permissions` so the AI-guided setup flow is uninterrupted.
14
+
-**Simpler `ralph new` experience** — the skill no longer asks users about checks, contexts, or frontmatter. Just describe what you want to automate in plain English and the agent builds the ralph for you.
15
+
-**`ralph new` knows about user arguments** — the skill can now suggest `{{ args.name }}` placeholders when a ralph would benefit from being reusable across projects.
description: Create a new ralph with prompt, checks, and contexts via guided conversation
3
+
description: Create a new ralph from a plain-English description of what you want to automate
4
4
argument-hint: "[name]"
5
5
disable-model-invocation: true
6
6
---
7
7
8
-
You are helping the user create a new **ralph** — a reusable task-focused prompt with checks and contexts for autonomous AI coding loops powered by [ralphify](https://github.com/computerlovetech/ralphify).
8
+
You are helping the user create a new **ralph** — a reusable automation for autonomous AI coding loops powered by ralphify. The user does NOT need to know how ralphify works internally. Your job is to translate their plain description into a working ralph setup.
9
9
10
-
## Ralphify primitives reference
10
+
## What you need from the user
11
11
12
-
A ralph lives at `.ralphify/ralphs/<name>/RALPH.md` and consists of:
12
+
Ask the user to **describe what they want to automate** in plain language. For example:
13
+
- "I want to write tests for my Python project until I hit 90% coverage"
14
+
- "I want to refactor all my JavaScript files to TypeScript"
15
+
- "I want to fix linting errors across the codebase"
13
16
14
-
### RALPH.md
17
+
If `$ARGUMENTS` was provided, use it as the ralph name. Otherwise, derive a short kebab-case name from their description.
18
+
19
+
Ask **only what you need** to build a good setup:
20
+
- What does "done" look like for one cycle of work?
21
+
- What language/tools/framework is the project using?
22
+
- Any conventions or constraints to follow?
23
+
24
+
Do NOT ask the user about checks, contexts, frontmatter, or other ralphify internals. Figure those out yourself based on their description.
25
+
26
+
## How ralphs work (internal reference — do not expose to user)
27
+
28
+
A ralph is a directory at `.ralphify/ralphs/<name>/` containing a prompt and optional validation and data injection.
29
+
30
+
### RALPH.md — the prompt
15
31
16
32
```markdown
17
33
---
18
34
description: What this ralph does (one line)
35
+
checks: [global-check-name] # optional: include global checks
36
+
contexts: [global-context-name] # optional: include global contexts
Your prompt content here. This is piped to the agent as stdin each iteration.
41
+
Prompt text piped to the agent each iteration.
42
+
Use {{ contexts.context-name }} to place context output.
43
+
Use {{ args.name }} for user arguments passed from the CLI.
23
44
```
24
45
25
-
### Checks
26
-
27
-
Checks validate the agent's work **after each iteration**. If a check fails, its output and failure instruction are appended to the next iteration's prompt.
- Body text appears as a label above the command output
62
-
- Contexts run regardless of command exit code
63
-
- Place contexts in the prompt with `{{ contexts.context-name }}` — each context must be referenced by name
77
+
- Reference in the prompt with `{{ contexts.context-name }}`
78
+
79
+
### User arguments
80
+
81
+
Ralphs can accept CLI arguments, making them reusable across different projects or configurations:
82
+
83
+
-**Named flags**: `ralph run research --dir ./src --focus "perf"` → `{{ args.dir }}`, `{{ args.focus }}`
84
+
-**Positional args**: `ralph run research ./src "perf"` — requires `args: [dir, focus]` in frontmatter
85
+
- Missing args resolve to empty string
86
+
- Context and check scripts receive them as `RALPH_ARG_<KEY>` environment variables (uppercase, hyphens → underscores)
87
+
88
+
Use args when a ralph could be reused across different directories, files, thresholds, or configurations.
64
89
65
90
### Scripts
66
91
67
-
For commands needing shell features (pipes, redirects, `&&`), create a `run.sh`or`run.py` in the primitive directory. If both a `command` and a `run.*` script exist, the script takes precedence. Remember to `chmod +x` scripts.
92
+
For commands needing shell features, create `run.sh`/`run.py` in the primitive directory. Script takes precedence over `command`. Remember `chmod +x`.
68
93
69
94
### Execution order
70
95
71
-
Primitives run in alphabetical order by directory name. Use number prefixes to control order: `01-lint/`, `02-tests/`.
96
+
Primitives run alphabetically. Use number prefixes: `01-lint/`, `02-tests/`.
72
97
73
98
### Output truncation
74
99
75
100
All primitive output is truncated to 5000 characters.
76
101
77
102
## Your workflow
78
103
79
-
1.**Get the ralph name.** If `$ARGUMENTS` was provided, use it as the ralph name (convert to kebab-case if needed). Otherwise, ask the user what task they want to automate and derive a short kebab-case name.
80
-
81
-
2.**Ask clarifying questions.** Understand the task well enough to write a good prompt:
82
-
- What does the agent need to accomplish each iteration?
83
-
- What codebase, language, or tools are involved?
84
-
- What validation matters? (tests, linting, type checking, builds, etc.)
85
-
- Are there existing patterns or conventions to follow?
86
-
87
-
3.**Create the RALPH.md** at `.ralphify/ralphs/<name>/RALPH.md` with:
88
-
- Frontmatter with a clear `description`
89
-
- A well-structured prompt that tells the agent:
90
-
- What it is and what it's doing
91
-
- That each iteration starts fresh (progress lives in code and git)
92
-
- Specific rules and constraints
93
-
- Where to place context output (use named placeholders like `{{ contexts.name }}`)
94
-
- Follow these prompt patterns:
95
-
- Start with role and loop awareness: "You are an autonomous X agent running in a loop."
96
-
- Include "Each iteration starts with a fresh context. Your progress lives in the code and git."
97
-
- Be specific about what "one iteration" means
98
-
- Include rules as a bulleted list
99
-
- End with commit message conventions
100
-
101
-
4.**Create checks** at `.ralphify/ralphs/<name>/checks/<check-name>/CHECK.md`:
102
-
- Always include relevant validation (tests, linting, type checking, builds)
103
-
- Write clear failure instructions that tell the agent HOW to fix the problem
104
-
- Use scripts (`run.sh`) when shell features are needed
104
+
1.**Understand the task.** Get a plain-English description. Ask short clarifying questions if needed — no more than 2-3.
105
105
106
-
5.**Create contexts**at `.ralphify/ralphs/<name>/contexts/<context-name>/CONTEXT.md` if useful:
107
-
-Git log for tracking progress across iterations
108
-
-Coverage reports for test-writing tasks
109
-
-File listings for navigation
110
-
-Use scripts for commands needing shell features
106
+
2.**Design the ralph.**Based on the description, decide:
107
+
-What prompt to write
108
+
-What checks will catch mistakes (tests, lint, type checks, builds, etc.)
109
+
-What context the agent needs each iteration (git log, coverage reports, file listings, etc.)
110
+
-Whether user arguments would make the ralph more reusable
111
111
112
-
6.**Set permissions** — run `chmod +x` on any `run.sh` or `run.py` scripts you create.
113
-
114
-
7.**Show a summary** of everything you created (file tree with paths).
115
-
116
-
8.**Suggest testing** with: `ralph run <name> -n 1`
112
+
3.**Create everything:**
113
+
-`RALPH.md` with a clear, specific prompt. Follow these patterns:
114
+
- Start with role and loop awareness: "You are an autonomous X agent running in a loop."
115
+
- Include: "Each iteration starts with a fresh context. Your progress lives in the code and git."
116
+
- Be specific about what one iteration of work looks like
117
+
- Include rules as a bulleted list
118
+
- End with commit conventions
119
+
- Checks for any validation that matters (tests, linting, type checking, builds)
120
+
- Contexts for dynamic data the agent needs
121
+
-`chmod +x` on any scripts
122
+
123
+
4.**Present a summary** to the user:
124
+
- Show the file tree of what you created
125
+
- Briefly explain what the ralph will do in each iteration
0 commit comments