@graypark/ralph-codex 0.2.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +108 -34
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,11 +34,57 @@ node bin/install.mjs --global
|
|
|
34
34
|
| `--dry-run` | Preview changes without modifying anything |
|
|
35
35
|
| `--force` | Overwrite existing installation |
|
|
36
36
|
|
|
37
|
-
|
|
37
|
+
### What Gets Installed
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
```
|
|
40
|
+
~/.codex/
|
|
41
|
+
├── plugins/ralph-codex/ # Core plugin files
|
|
42
|
+
├── hooks.json # Stop hook registration (merged)
|
|
43
|
+
└── skills/
|
|
44
|
+
├── ralph-loop/ # /ralph-loop command
|
|
45
|
+
├── cancel-ralph/ # /cancel-ralph command
|
|
46
|
+
└── ralph-interview/ # /ralph-interview command
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Commands
|
|
50
|
+
|
|
51
|
+
### `/ralph-interview` — Generate Optimized Commands
|
|
52
|
+
|
|
53
|
+
**The easiest way to get started.** This interactive skill interviews you about your task and generates a perfectly structured `/ralph-loop` command.
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
/ralph-interview
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**How it works:**
|
|
60
|
+
|
|
61
|
+
1. Describe your task (e.g., "Add auth to our API")
|
|
62
|
+
2. The interview asks 3–5 targeted questions (scope, success criteria, verification commands, etc.)
|
|
63
|
+
3. It generates a copy-paste-ready `/ralph-loop` command with:
|
|
64
|
+
- Proper phase separation (analysis vs. implementation)
|
|
65
|
+
- Self-correcting work cycles (modify → verify → retry)
|
|
66
|
+
- Escape hatches for when you're stuck
|
|
67
|
+
- Objective completion criteria
|
|
68
|
+
- Atomic git commits per work item
|
|
69
|
+
|
|
70
|
+
**Auto-execute mode:** Add "run immediately" or "바로 실행" to skip the confirmation step:
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
/ralph-interview Add pagination to the users API, run immediately
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
After generating, it will ask:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
Ready to run?
|
|
80
|
+
- y / yes → Start Phase 1 immediately
|
|
81
|
+
- n / no → Commands are above, copy-paste when ready
|
|
82
|
+
- edit → Tell me what to change
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### `/ralph-loop` — Run a Loop Directly
|
|
40
86
|
|
|
41
|
-
|
|
87
|
+
If you already know how to write a good prompt:
|
|
42
88
|
|
|
43
89
|
```
|
|
44
90
|
/ralph-loop "Build a REST API for todos with CRUD, validation, and tests" --max-iterations 30 --completion-promise "ALL_TESTS_PASS"
|
|
@@ -52,54 +98,76 @@ In Codex CLI, use the slash command:
|
|
|
52
98
|
| `--max-iterations N` | 20 | Maximum loop iterations (0 = unlimited) |
|
|
53
99
|
| `--completion-promise TEXT` | "TADA" | Phrase that signals task completion |
|
|
54
100
|
|
|
55
|
-
###
|
|
101
|
+
### `/cancel-ralph` — Stop the Loop
|
|
56
102
|
|
|
57
103
|
```
|
|
58
104
|
/cancel-ralph
|
|
59
105
|
```
|
|
60
106
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
Don't know how to write a good ralph-loop prompt? Let the interview skill help:
|
|
107
|
+
## How the Loop Works
|
|
64
108
|
|
|
65
109
|
```
|
|
66
|
-
|
|
110
|
+
┌─────────────────────────────────────────────┐
|
|
111
|
+
│ /ralph-loop "Build feature X" │
|
|
112
|
+
│ │
|
|
113
|
+
│ ┌──────────┐ ┌──────────┐ │
|
|
114
|
+
│ │ Codex │───▶│ Works │ │
|
|
115
|
+
│ │ starts │ │ on task │ │
|
|
116
|
+
│ └──────────┘ └────┬─────┘ │
|
|
117
|
+
│ │ │
|
|
118
|
+
│ ▼ │
|
|
119
|
+
│ ┌──────────────┐ │
|
|
120
|
+
│ │ Tries to exit │ │
|
|
121
|
+
│ └───────┬──────┘ │
|
|
122
|
+
│ │ │
|
|
123
|
+
│ ▼ │
|
|
124
|
+
│ ┌───────────────────┐ │
|
|
125
|
+
│ │ Stop Hook │ │
|
|
126
|
+
│ │ ┌───────────────┐ │ │
|
|
127
|
+
│ │ │ Max reached? │─┼──Yes──▶ EXIT
|
|
128
|
+
│ │ │ Promise found?│─┼──Yes──▶ EXIT
|
|
129
|
+
│ │ └───────┬───────┘ │ │
|
|
130
|
+
│ │ No │ │
|
|
131
|
+
│ │ │ │ │
|
|
132
|
+
│ │ Block exit + │ │
|
|
133
|
+
│ │ re-inject prompt │ │
|
|
134
|
+
│ └─────────┬─────────┘ │
|
|
135
|
+
│ │ │
|
|
136
|
+
│ ▼ │
|
|
137
|
+
│ ┌──────────────┐ │
|
|
138
|
+
│ │ Codex sees │ │
|
|
139
|
+
│ │ previous work│──── loop ────┘
|
|
140
|
+
│ └──────────────┘
|
|
67
141
|
```
|
|
68
142
|
|
|
69
|
-
It asks 3–5 targeted questions about your task, then generates an optimized `/ralph-loop` command with proper phases, escape hatches, verification steps, and completion criteria.
|
|
70
|
-
|
|
71
|
-
### How It Works
|
|
72
|
-
|
|
73
|
-
1. You invoke `/ralph-loop` with a task prompt
|
|
74
|
-
2. Codex works on the task normally
|
|
75
|
-
3. When Codex tries to exit, the **Stop hook** intercepts
|
|
76
|
-
4. The hook checks: max iterations reached? Completion promise found?
|
|
77
|
-
5. If not done, the hook **blocks the exit** and feeds the same prompt back
|
|
78
|
-
6. Codex sees its previous work in files and git history
|
|
79
|
-
7. Codex continues iterating until completion
|
|
80
|
-
|
|
81
143
|
### Completion Promise
|
|
82
144
|
|
|
83
|
-
To signal task completion, Codex must output the promise phrase
|
|
145
|
+
To signal task completion, Codex must output the promise phrase in XML tags:
|
|
84
146
|
|
|
85
147
|
```
|
|
86
148
|
<promise>ALL_TESTS_PASS</promise>
|
|
87
149
|
```
|
|
88
150
|
|
|
89
|
-
The promise is only valid when the statement is genuinely true. The loop
|
|
151
|
+
The promise is only valid when the statement is genuinely true. The loop prevents false exits.
|
|
90
152
|
|
|
91
153
|
## Prompt Writing Tips
|
|
92
154
|
|
|
155
|
+
> **Tip:** Use `/ralph-interview` instead of writing prompts manually. It handles all of these patterns for you.
|
|
156
|
+
|
|
93
157
|
### 1. Split into Phases
|
|
94
158
|
|
|
95
159
|
```
|
|
96
|
-
/ralph-loop "Phase 1: Set up project scaffold.
|
|
160
|
+
/ralph-loop "Phase 1: Set up project scaffold.
|
|
161
|
+
Phase 2: Implement core logic.
|
|
162
|
+
Phase 3: Add tests.
|
|
163
|
+
Output <promise>DONE</promise> when all phases complete." --max-iterations 30
|
|
97
164
|
```
|
|
98
165
|
|
|
99
166
|
### 2. Objective Completion Criteria
|
|
100
167
|
|
|
101
168
|
```
|
|
102
|
-
/ralph-loop "Implement the auth module.
|
|
169
|
+
/ralph-loop "Implement the auth module.
|
|
170
|
+
Done when: all tests pass, no TypeScript errors, coverage > 80%." --completion-promise "AUTH_COMPLETE" --max-iterations 25
|
|
103
171
|
```
|
|
104
172
|
|
|
105
173
|
### 3. Always Set an Escape Hatch
|
|
@@ -135,7 +203,7 @@ This removes:
|
|
|
135
203
|
|
|
136
204
|
- Plugin files from `~/.codex/plugins/ralph-codex/`
|
|
137
205
|
- Stop hook entry from `~/.codex/hooks.json`
|
|
138
|
-
-
|
|
206
|
+
- All skill files (`ralph-loop`, `cancel-ralph`, `ralph-interview`)
|
|
139
207
|
- Any active state file
|
|
140
208
|
|
|
141
209
|
## Architecture
|
|
@@ -143,17 +211,22 @@ This removes:
|
|
|
143
211
|
```
|
|
144
212
|
ralph-codex/
|
|
145
213
|
├── bin/
|
|
146
|
-
│ ├── install.mjs
|
|
147
|
-
│ └── uninstall.mjs
|
|
214
|
+
│ ├── install.mjs # Cross-platform installer
|
|
215
|
+
│ └── uninstall.mjs # Clean uninstaller
|
|
148
216
|
├── hooks/
|
|
149
|
-
│ ├── hooks.json
|
|
150
|
-
│ └── stop-hook.mjs
|
|
217
|
+
│ ├── hooks.json # Hook registration (reference)
|
|
218
|
+
│ └── stop-hook.mjs # Stop hook — the core loop engine
|
|
151
219
|
├── commands/
|
|
152
|
-
│ ├── ralph-loop.md
|
|
153
|
-
│ └── cancel-ralph.md
|
|
220
|
+
│ ├── ralph-loop.md # /ralph-loop slash command
|
|
221
|
+
│ └── cancel-ralph.md # /cancel-ralph slash command
|
|
222
|
+
├── skills/
|
|
223
|
+
│ └── ralph-interview/
|
|
224
|
+
│ └── SKILL.md # /ralph-interview — interactive command generator
|
|
154
225
|
├── lib/
|
|
155
|
-
│ ├── paths.mjs
|
|
156
|
-
│
|
|
226
|
+
│ ├── paths.mjs # Cross-platform path utilities
|
|
227
|
+
│ ├── state.mjs # Loop state management
|
|
228
|
+
│ └── stop-hook-core.mjs # Testable stop hook logic
|
|
229
|
+
├── tests/ # 32 test cases (vitest)
|
|
157
230
|
└── package.json
|
|
158
231
|
```
|
|
159
232
|
|
|
@@ -167,6 +240,7 @@ ralph-codex/
|
|
|
167
240
|
| Hook protocol | `{"decision":"block","reason":"..."}` | Same |
|
|
168
241
|
| Transcript parsing | `jq` + `grep` | Native Node.js |
|
|
169
242
|
| Installation | Plugin marketplace | `npx` or manual |
|
|
243
|
+
| Command generator | None | `/ralph-interview` |
|
|
170
244
|
|
|
171
245
|
## Development
|
|
172
246
|
|
|
@@ -174,7 +248,7 @@ ralph-codex/
|
|
|
174
248
|
# Install dev dependencies
|
|
175
249
|
npm install
|
|
176
250
|
|
|
177
|
-
# Run tests
|
|
251
|
+
# Run tests (32 cases)
|
|
178
252
|
npm test
|
|
179
253
|
|
|
180
254
|
# Run tests in watch mode
|