minimal-agent 0.8.2 → 0.10.0

package/workflows/youtube-shorts.yaml

@@ -7,32 +7,40 @@ description: |
   去做任意视频流水线（横屏长视频、广告片、教程片都行）。
 version: "0.1"
 
+# 声明产物：new-task 启动清理残留 / completed 报实际产物 / 同任务 resume 重写不被
+# 内核「覆盖前先 Read」守卫挡（见 CLAUDE.md 任务身份语义）
+artifacts:
+  - "./assets/script.json"
+  - "./out/shorts.mp4"
+
 inputs:
   - name: topic
     type: string
     required: true
-    description: "视频主题（中文）"
+    greedy: true
+    description: "视频主题（中文，可一句话自然语言；命令行整句进 topic，不被空格拆碎）"
   - name: openrouter_key
     type: string
     required: false
-    description: "OpenRouter API key；不填则用 OPENROUTER_API_KEY 环境变量"
+    description: "【高级·用 --input openrouter_key=...】OpenRouter API key；不填则用 OPENROUTER_API_KEY 环境变量"
   - name: aspect
     type: enum
     values: ["9:16", "16:9", "1:1", "4:5"]
     default: "9:16"
-    description: "图片与视频宽高比"
+    description: "【高级·用 --input aspect=...】图片与视频宽高比"
   - name: width
     type: number
     default: 1080
-    description: "视频输出宽度"
+    description: "【高级·用 --input width=N】视频输出宽度"
   - name: height
     type: number
     default: 1920
-    description: "视频输出高度"
+    description: "【高级·用 --input height=N】视频输出高度"
 
 steps:
   # ---------- 1. 用 LLM 写 5 幕脚本（强制 5 幕以便后续 loop 用静态数组） ----------
   - id: write_script
+    title: "1/11·写五幕脚本"
     llm: |
       你是短视频文案策划。请为主题"${inputs.topic}"写一个 **正好 5 幕** 的竖屏短视频。
       每一幕包含：
@@ -48,13 +56,17 @@ steps:
 
   # ---------- 2. 把 LLM 输出落盘为 script.json ----------
   - id: write_script_json
+    title: "2/11·脚本落盘 script.json"
     tool: Write
+    artifacts:
+      - "./assets/script.json"
     args:
       file_path: "./assets/script.json"
       content: "${script_json_text}"
 
   # ---------- 3. 解析 script.json，拆出 prompts.txt / narrations.txt（每行一个） ----------
   - id: parse_script
+    title: "3/11·解析脚本拆分文案"
     tool: Bash
     args:
       command: |
@@ -69,44 +81,57 @@ steps:
       content: parse_log
 
   - id: assert_script_parsed
-    type: assert
-    condition: 'fileExists("./assets/prompts.txt") && fileExists("./assets/narrations.txt")'
+    title: "4/11·校验脚本拆分产物"
+    type: verify
+    checks:
+      - 'file_exists:./assets/prompts.txt'
+      - 'file_exists:./assets/narrations.txt'
     onFail: "脚本解析失败：./assets/prompts.txt 或 ./assets/narrations.txt 不存在"
 
   # ---------- 4. 生成 5 张配图（loop 静态数组 + 每轮先读对应一行 prompt） ----------
+  # ⚠️ Bash 引号 footgun：${i} 是引擎插值（shell 之前发生）。曾写 1 基算术
+  # `sed -n '$((${i}+1))p'`——shell 单引号内不做算术展开，sed 收到字面 $((0+1))p
+  # 直接报错。正解：loop 直接用 1 基序号，sed 行号即 ${i}。
   - id: gen_images
+    title: "5/11·生成五张配图"
     type: loop
-    over: "[0, 1, 2, 3, 4]"
+    over: "[1, 2, 3, 4, 5]"
     as: i
     do:
       - id: read_prompt
+        title: "读第 ${i} 行画面提示词"
         tool: Bash
         args:
-          command: "sed -n '$((${i}+1))p' ./assets/prompts.txt"
+          command: 'sed -n "${i}p" ./assets/prompts.txt'
         capture:
           content: prompt_text
       - id: gen_one_image
+        title: "生成第 ${i} 张配图"
         skill: image-gen-openrouter
         input: 'prompt=${prompt_text} output=./assets/img_${i}.png aspect=${inputs.aspect} key=${inputs.openrouter_key}'
 
-  # ---------- 5. 生成 5 段 TTS 音频 ----------
+  # ---------- 5. 生成 5 段 TTS 音频（1 基序号，理由同 gen_images） ----------
   - id: gen_audio
+    title: "6/11·生成五段配音"
     type: loop
-    over: "[0, 1, 2, 3, 4]"
+    over: "[1, 2, 3, 4, 5]"
     as: i
     do:
       - id: read_narration
+        title: "读第 ${i} 句旁白"
         tool: Bash
         args:
-          command: "sed -n '$((${i}+1))p' ./assets/narrations.txt"
+          command: 'sed -n "${i}p" ./assets/narrations.txt'
         capture:
           content: narration_text
       - id: gen_one_tts
+        title: "合成第 ${i} 段语音"
         skill: tts-zh
         input: 'text=${narration_text} output=./assets/audio_${i}.mp3'
 
   # ---------- 6. 探测各段音频时长，逗号串联 ----------
   - id: probe_durations
+    title: "7/11·探测音频时长"
     tool: Bash
     args:
       command: |
@@ -119,6 +144,7 @@ steps:
 
   # ---------- 7. 合并所有 TTS 段成一条音轨 ----------
   - id: merge_audio
+    title: "8/11·合并音轨"
     tool: Bash
     args:
       command: |
@@ -133,6 +159,7 @@ steps:
 
   # ---------- 8. 读 narrations_json（前面 parse_script 已写好），作 SRT 文本输入 ----------
   - id: read_narrations_json
+    title: "9/11·读取旁白清单"
     tool: Read
     args:
       file_path: "./assets/narrations_json.txt"
@@ -141,18 +168,22 @@ steps:
 
   # ---------- 9. 生成 SRT 字幕 ----------
   - id: make_srt
+    title: "10/11·生成字幕"
     skill: subtitle-srt
     input: 'texts=${narrations_json} durations=${durations} output=./assets/subs.srt'
 
   # ---------- 10. 合成最终 mp4 ----------
   - id: compose_video
+    title: "11/11·合成最终视频"
     skill: video-compose
     input: 'images_glob=./assets/img_*.png audio=./assets/audio.mp3 srt=./assets/subs.srt output=./out/shorts.mp4 width=${inputs.width} height=${inputs.height}'
 
-  # ---------- 11. 守门 assert ----------
+  # ---------- 11. 守门 verify（升级自 assert） ----------
   - id: verify_output
-    type: assert
-    condition: 'fileExists("./out/shorts.mp4")'
+    title: "完成·守门校验"
+    type: verify
+    checks:
+      - 'file_exists:./out/shorts.mp4'
     onFail: "最终视频 ./out/shorts.mp4 未生成，请检查 video-compose 日志"
 
 __meta:

package/MINIMAL-TRACE.md

@@ -1,77 +0,0 @@
-# MINIMAL-TRACE —— 用最短路径读懂 agent 主循环
-
-> 教学导读。本项目首要目标是「讲透一个 agent 从输入 → 工具循环 → 落盘」。
-> 但 `src/loop.ts` 已含不少**生产硬化**（4 种压缩 / 反应式自救 / 并行事件队列 / 截断警告…），
-> 初学者直接读会被淹没。这篇带你**第一遍只看主干**，把硬化层全部圈出来跳过。
-
-## 一句话本质
-
-```
-用户输入 → 调 LLM → LLM 想调工具就执行 → 结果喂回 → 再调 LLM → … → 不调工具了，输出最终回答
-```
-
-整个 agent 就是这个循环。它写在 `src/loop.ts::runQuery`（一个 `async function*`，逐步 `yield` 事件给 UI）。
-
-## 最小可读路径（第一遍只看这 6 步）
-
-打开 `src/loop.ts`，找到 `runQuery`，顺着看这几段——**只看主干，遇到下面「进阶层」列出的东西先跳过**：
-
-1. **用户消息入栈**：把 `{ role:'user', content: userInput }` push 进 `history`，`yield` 一个 `user_message_committed` 让 UI 先把它显示出来。`history` 是一个会被原地 mutate 的数组（调用方和 loop 共享同一引用）。
-
-2. **进入 `while (turn < maxTurns)`**：每一轮 = 一次「调 LLM（可能带工具）」。`maxTurns`（默认 50）是失控保护。
-
-3. **调 LLM、把流式响应拼成一条 assistant 消息**：`for await (const ev of chat({...}))` 逐块消费——`text_delta` 累积成答案文本并 `yield {type:'text'}`；`tool_call_delta` 累积成工具调用（OpenAI 协议下工具调用也是分片返回的，用 `mergeToolCallDelta` 合并）。循环结束后组装出 `assistantMsg` 推入 `history`、`yield assistant_message`。
-
-4. **没有工具调用 → 这一轮就是最终回答，结束**：`if (toolCallsByIndex.length === 0)` → `yield {type:'turn_done'}` 然后 `return`。这是循环的正常出口。
-
-5. **有工具调用 → 逐个执行、把结果按顺序回填 `history`**：对每个工具调用，`yield tool_start` → 调 `executeToolFn(name, argsJson, signal)` → `yield tool_end`，再把结果作为 `{ role:'tool', tool_call_id }` 消息 push 回 `history`。**关键**：tool 消息必须严格按 assistant 的 `tool_calls` 顺序回填（OpenAI 协议要求一一对应）。
-
-6. **回到 `while` 顶部继续下一轮**：模型这次能看到上一轮的工具结果，于是接着推理——要么再调工具，要么给出最终答案（回到第 4 步出口）。
-
-读完这 6 步，你就掌握了 agent 的全部本质。下面的都是「让它在生产环境不出岔子」的加固，第一遍可以完全不看。
-
-## 进阶层（第一遍请跳过）
-
-这些都是 `runQuery` 里为了**健壮/体验**加的料，每个解决一个具体问题，但都不影响你理解主循环：
-
-| 你会看到 | 它解决什么 | 第一遍 |
-|---|---|---|
-| `autoCompactIfNeeded`（每轮开头） | 上下文快撑爆时，把旧对话压成摘要，防止超 contextWindow | 跳过 |
-| `reactiveCompactIfApplicable`（catch 里） | 真撞上 prompt-too-long 时，压缩历史后**同轮重发**自救 | 跳过 |
-| `snipCompactIfNeeded`（压缩失败兜底） | 连压缩都失败时，硬砍最老消息释放空间再继续 | 跳过 |
-| `microCompact`（回填 tool 结果时） | 把单个超长工具输出就地压短，省 token | 跳过 |
-| `allConcurrencySafe` 分支 + 事件队列 | 本轮工具**全是只读**才并行执行，否则串行（杜绝并行写同一文件） | 跳过 |
-| `lastFinishReason === 'length'` 警告 | 模型答案被 max_tokens 截断时提醒用户「这是半截」 | 跳过 |
-| `reasoningContent / reasoning / reasoning_details` | 累积思维链（DeepSeek-R1 / MiniMax 等），下一轮原样回传防「失忆」 | 跳过 |
-| `error` 事件的 `code`（llm_error / max_turns / …） | 让 `-p --output-format json` 把终结原因映射成稳定的 stop_reason（给宿主 spawn 用） | 跳过 |
-| `options.chat` / `options.executeTool` | 依赖注入：测试时传 stub，零进程污染；生产走真实模块单例 | 跳过 |
-
-## 时序图（主干）
-
-```
-用户输入
-   │
-   ▼
-runQuery  ──push user 消息──►  history
-   │
-   ├─◄─────────────────────────┐  （每轮 turn）
-   ▼                           │
- chat(LLM)  ──流式 text / tool_call──►  拼成 assistant 消息 → history
-   │                           │
-   ├── 无 tool_calls ──► turn_done ──► return（最终回答）
-   │                           │
-   └── 有 tool_calls           │
-        │                      │
-        ▼                      │
-   executeTool ×N ──► tool 结果 → history ──┘（回到下一轮，模型看到结果再推理）
-```
-
-## 延伸阅读（按需，第几步用到再看）
-
-- **`src/types.ts`** —— 类型字典。先看 `Message`（4 种 role）、`ToolCall`、`LlmStreamEvent`（LLM 流式块）、`LoopEvent`（loop 给 UI 的事件）。读主循环前先扫一遍这四个就够。
-- **`src/llm/client.ts`** —— `chat()` 的实现：把 provider 的 SSE 流解析成 `LlmStreamEvent`。对应主干第 3 步。
-- **`src/tools/index.ts`** —— `ALL_TOOLS`（工具清单）+ `executeTool()`：参数防线（JSON.parse → Zod 校验 → 调 `tool.call()`，**工具失败不抛异常**，把 error 喂回 LLM 让它重试）。对应主干第 5 步。
-- **`src/context/compact.ts`** —— 自动压缩入口（进阶层）。想搞懂「上下文怎么不撑爆」再看。
-- **`src/loop.ts`** —— 主角本身。读完本文按上面 6 步对照源码，再回头看进阶层。
-
-> 一句话给初学者：**先把 6 步主干跑通，把进阶层当黑盒**；等你能复述「输入怎么变成最终回答」了，再一个个揭开硬化层——每揭开一个，你就多懂一点「为什么生产级 agent 不只是一个 while 循环」。

package/plugins/HOW-TO-WRITE-A-PLUGIN.md

@@ -1,186 +0,0 @@
-# How to Write a minimal-agent Plugin
-
-minimal-agent 的插件系统遵循 **drop-in** 原则：把目录扔进 `plugins/`，命令立即可用，**`src/` 一行不改**。
-
-## 两种契约
-
-### 1. 纯声明式（Anthropic 兼容，零 TS）
-
-最小可用插件 = 一个 frontmatter 模板。框架替你拼 prompt 喂给 LLM。
-
-```
-plugins/hello-bot/
-├── .claude-plugin/
-│   └── plugin.json
-└── commands/
-    └── hi.md
-```
-
-**`.claude-plugin/plugin.json`**
-
-```json
-{
-  "name": "hello-bot",
-  "version": "0.1.0",
-  "description": "Greets the user"
-}
-```
-
-**`commands/hi.md`**
-
-```markdown
----
-description: "Greet the user"
-argument-hint: "<name>"
----
-
-你好 $ARGUMENTS！欢迎使用 minimal-agent。
-```
-
-**效果**：用户输入 `/hi 世界` → LLM 收到 `你好 世界！欢迎使用 minimal-agent。\n\n用户参数: 世界`。
-
-支持的占位符：
-- `$ARGUMENTS` / `${ARGUMENTS}` —— 用户在命令名后的全部文本
-- `${CLAUDE_PLUGIN_ROOT}` —— 该插件目录的绝对路径（用于引用插件资源）
-
-### 2. 声明式 + `plugin.ts`（富插件）
-
-当模板不够（要跑循环 / 做 TS 校验 / 启动子进程 / 状态机），加一个 `plugin.ts`：
-
-```
-plugins/echo-bot/
-├── .claude-plugin/plugin.json
-├── commands/echo.md         # 仍要存在！frontmatter 用于 listAvailableCommands
-└── plugin.ts                # PluginApi default export
-```
-
-**`plugin.ts`**
-
-```typescript
-import {
-  runQuery,
-  type PluginApi,
-  type LoopEvent,
-} from '../../src/plugin-sdk.ts';
-
-const api: PluginApi = {
-  async *runCommand(commandName, args, ctx): AsyncGenerator<LoopEvent> {
-    if (commandName === 'echo') {
-      // 直接 yield 自定义事件
-      yield { type: 'text', delta: `你输入了：${args}` };
-      yield { type: 'turn_done' };
-      return;
-    }
-
-    // 或者改写 prompt 后丢给 LLM
-    yield* runQuery(`请把以下内容重复 3 遍：${args}`, {
-      provider: ctx.provider,
-      history: ctx.history,
-      signal: ctx.signal,
-    });
-  },
-};
-
-export default api;
-```
-
-**框架行为**：命中 `/echo abc` 时，`pluginRunner` 优先调用 `runCommand('echo', 'abc', ctx)`，不再走声明式 fallback。你完全接管事件流。
-
-## `plugin-sdk.ts` 暴露的全部 API
-
-**唯一稳定 import 路径**：`from '../../src/plugin-sdk.ts'`（相对你的 `plugin.ts`）。
-
-| 名称 | 类型 | 用途 |
-|------|------|------|
-| `runQuery(input, opts)` | function | 标准 T-A-O-R 循环，AsyncGenerator |
-| `chat(messages, provider, opts)` | function | 单次非流式 LLM 调用 |
-| `executeTool(name, argsJson, ctx)` | function | 框架级工具调用入口 |
-| `getToolByName(name)` | function | 取 Tool 定义 |
-| `ALL_TOOLS` | const | 所有内置工具数组 |
-| `getWorkingDir()` | function | 当前锁定的工作目录 |
-| `getResourceSearchPaths(name, importMetaUrl)` | function | 双源资源路径（cwd + packageRoot） |
-| `triggerHook(event, payload)` | function | 触发框架级 hook |
-| `createSessionState()` | function | 新建 SessionState |
-| `Message` / `Provider` / `LoopEvent` / `LlmStreamEvent` | type | 协议类型 |
-| `Tool` / `ToolCall` / `ToolResult` | type | 工具协议类型 |
-| `PluginApi` / `PluginContext` | type | 你的 plugin.ts 契约 |
-| `ResourceName` / `HookEventName` / `HookDecision` / `SessionState` | type | 杂项 |
-
-**不要**绕开 `plugin-sdk.ts` 直接 import `src/loop.ts` / `src/llm/client.ts` 等内部路径 —— 那些路径不是稳定 API，框架重构时会破坏你的插件。
-
-## `PluginContext`
-
-`runCommand` 收到的 ctx：
-
-```typescript
-interface PluginContext {
-  provider: Provider;          // 当前 LLM provider 配置
-  history: Message[];          // 对话历史（你可以读 / 修改 / 替换）
-  signal?: AbortSignal;        // 用户 ESC / Ctrl+C 时触发
-  sessionState?: SessionState; // 可选共享 session 状态
-  maxTurns?: number;           // 工具循环最大轮数（runQuery 透传用）
-}
-```
-
-## 事件 (`LoopEvent`)
-
-你的 `runCommand` 必须 yield `LoopEvent`，UI 据此渲染。常用的有：
-
-| type | 字段 | 用途 |
-|------|------|------|
-| `text` | `delta: string` | 流式文本片段 |
-| `assistant_message` | (无) | 一次完整 assistant 消息已 push 进 history |
-| `tool_start` | `toolName`, `argsPreview` | 工具开始执行 |
-| `tool_end` | (无) | 工具结束 |
-| `turn_done` | (无) | 整轮交互结束 |
-| `interrupted` | (无) | 用户中断 |
-| `error` | `error: string` | 红色错误提示 |
-| `plugin_progress` | `pluginId`, `current`, `max?`, `message?` | 循环进度条（替代旧的 plugin_start / plugin_iteration） |
-
-通常做法：复杂插件直接 `yield* runQuery(...)` 透传所有事件，自己额外 yield `plugin_progress` 做进度展示。
-
-## 工作目录与持久化
-
-- 状态写到 `getWorkingDir()/.minimal-agent-<your-plugin-id>/` 下，避免污染主 context 目录
-- `/new` 命令会自动清这些 `.minimal-agent*` 目录，你不用管 cleanup
-- 跨平台：Windows 没 bash，hooks/*.sh 静默跳过；其它 .ts 代码完全平台无关
-
-## 命令默认值
-
-框架**不再**注入命令默认参数（旧版 `COMMAND_DEFAULTS` 已删除）。如果你的命令需要默认值（如 `--max-iterations 50`），自己在 `plugin.ts` 里解析 args 时兜底。这样默认值的语义属于插件契约，不属于框架。
-
-## 测试
-
-- 把测试放在 `plugins/<id>/test/*.test.ts`
-- `bunfig.toml` 的 `[test].root = ["./test", "./plugins"]` 让 `bun test` 自动发现
-- 测试里 mock LLM / 工具时，用 `mock.module('../../../src/loop.ts', ...)` 等绝对到 src 的相对路径
-
-## 参考实现
-
-- **声明式 + plugin.ts 简单例**：`plugins/workflow-runner/plugin.ts`（~25 行接管 `/workflow` 与 `/workflows`）
-- **重型循环例**：`plugins/ralph-wiggum/plugin.ts`（~270 行 do-while loop + FSM + sentinel + verification + stop-hook）
-
-## Transcript 与 Hook：当前状态
-
-框架提供了两套基础设施 —— 都**就绪、有测试、可独立调用**，但**主循环 `src/loop.ts` 不自动触发**：
-
-| 模块 | 暴露 | 当前主循环触发？ |
-|------|------|------|
-| `src/plugins/transcript.ts` | `initTranscript / appendUserMessage / appendAssistantMessage / appendToolResult` | 否 |
-| `src/plugins/hookEngine.ts` | `loadHooks / triggerHook('UserPromptSubmit' \| 'PreToolUse' \| 'PostToolUse' \| 'SessionStart' \| 'SessionEnd', payload)` | 否 |
-
-**插件如何使用**：
-- 想写自己的 JSONL transcript → 在 `runCommand` 内 `import { initTranscript, appendUserMessage } from '../../src/plugin-sdk.ts'` 自己调
-- 想响应 hook 事件 → 在 `runCommand` 内 `triggerHook('PreToolUse', { tool_name, ... })` 自己调；ralph-wiggum 走的就是这条路（vendored stop-hook 执行器在 `plugins/ralph-wiggum/src/stopHookRunner.ts`）
-
-**为什么不在主循环自动触发**：当前没有 Anthropic 风格 `hooks/*.sh` 的真实用例驱动；自动触发会改主循环热路径但不解决实际问题。等真有跨插件的全局 hook 需求时再接也不迟。届时只需在 `src/loop.ts` 的 user/assistant/tool 三处 push 点加 `appendXxx` 与 `triggerHook` 调用即可，**不影响插件契约**。
-
-## 不支持的 Anthropic 字段
-
-minimal-agent 的插件契约是 Anthropic 上游的**子集**。当前未实现的字段：
-
-- `mcp-servers/` —— MCP 服务器配置
-- `agents/` —— 子 agent 定义
-- `skills/` 在插件目录下 —— minimal-agent 的 skill 系统是独立顶层目录
-
-未实现字段在 plugin.json 中存在不会报错，但被忽略。

package/plugins/ralph-wiggum/.claude-plugin/plugin.json

@@ -1,9 +0,0 @@
-{
-  "name": "ralph-wiggum",
-  "version": "1.0.0",
-  "description": "Implementation of the Ralph Wiggum technique - continuous self-referential AI loops for interactive iterative development. Run Claude in a while-true loop with the same prompt until task completion.",
-  "author": {
-    "name": "Daisy Hollman",
-    "email": "daisy@anthropic.com"
-  }
-}

package/plugins/ralph-wiggum/README.md

@@ -1,197 +0,0 @@
-# Ralph Wiggum Plugin
-
-Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Minimal Agent.
-
-## What is Ralph?
-
-Ralph is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: **"Ralph is a Bash loop"** - a simple `while true` that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.
-
-The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.
-
-### Core Concept
-
-This plugin implements Ralph using a **Stop hook** that intercepts Minimal Agent's exit attempts:
-
-```bash
-# You run ONCE:
-/ralph-loop "Your task description" --completion-promise "DONE"
-
-# Then Claude Code automatically:
-# 1. Works on the task
-# 2. Tries to exit
-# 3. Stop hook blocks exit
-# 4. Stop hook feeds the SAME prompt back
-# 5. Repeat until completion
-```
-
-The loop happens **inside your current session** - you don't need external bash loops. The Stop hook in `hooks/stop-hook.sh` creates the self-referential feedback loop by blocking normal session exit.
-
-This creates a **self-referential feedback loop** where:
-- The prompt never changes between iterations
-- Claude's previous work persists in files
-- Each iteration sees modified files and git history
-- Claude autonomously improves by reading its own past work in files
-
-## Quick Start
-
-```bash
-/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50
-```
-
-Claude will:
-- Implement the API iteratively
-- Run tests and see failures
-- Fix bugs based on test output
-- Iterate until all requirements met
-- Output the completion promise when done
-
-## Commands
-
-### /ralph-loop
-
-Start a Ralph loop in your current session.
-
-**Usage:**
-```bash
-/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
-```
-
-**Options:**
-- `--max-iterations <n>` - Stop after N iterations (default: 50, hard cap: 200)
-- `--completion-promise <text>` - Phrase that signals completion (natively active; default: DONE / COMPLETE / GOAL_COMPLETE)
-- `--verify "<CHECK>"` - Completion gate run after the promise tag. All checks must pass before the loop exits. Repeatable.
-  - `shell:<cmd>` — exit code 0 = pass (Windows: `cmd /c`, others: `bash -c`)
-  - `file_exists:<path>` — file must exist
-  - `file_contains:<file>:<regex>` — file content matches regex
-  - `test_count:<min>` — `bun test` pass count ≥ min
-
-  Example:
-  ```bash
-  /ralph-loop "Implement and test cache layer" \
-    --verify "shell:bun test" \
-    --verify "file_exists:dist/index.js"
-  ```
-
-### /cancel-ralph
-
-Cancel the active Ralph loop.
-
-**Usage:**
-```bash
-/cancel-ralph
-```
-
-## Prompt Writing Best Practices
-
-### 1. Clear Completion Criteria
-
-❌ Bad: "Build a todo API and make it good."
-
-✅ Good:
-```markdown
-Build a REST API for todos.
-
-When complete:
-- All CRUD endpoints working
-- Input validation in place
-- Tests passing (coverage > 80%)
-- README with API docs
-- Output: <promise>COMPLETE</promise>
-```
-
-### 2. Incremental Goals
-
-❌ Bad: "Create a complete e-commerce platform."
-
-✅ Good:
-```markdown
-Phase 1: User authentication (JWT, tests)
-Phase 2: Product catalog (list/search, tests)
-Phase 3: Shopping cart (add/remove, tests)
-
-Output <promise>COMPLETE</promise> when all phases done.
-```
-
-### 3. Self-Correction
-
-❌ Bad: "Write code for feature X."
-
-✅ Good:
-```markdown
-Implement feature X following TDD:
-1. Write failing tests
-2. Implement feature
-3. Run tests
-4. If any fail, debug and fix
-5. Refactor if needed
-6. Repeat until all green
-7. Output: <promise>COMPLETE</promise>
-```
-
-Tag lessons inline with `<learning>…</learning>` — the driver archives them to `learnings.md` automatically, so subsequent iterations inherit the hard-won knowledge without repeating mistakes.
-
-### 4. Escape Hatches
-
-Always use `--max-iterations` as a safety net to prevent infinite loops on impossible tasks:
-
-```bash
-# Recommended: Always set a reasonable iteration limit
-/ralph-loop "Try to implement feature X" --max-iterations 20
-
-# In your prompt, include what to do if stuck:
-# "After 15 iterations, if not complete:
-#  - Document what's blocking progress
-#  - List what was attempted
-#  - Suggest alternative approaches"
-```
-
-Claude can also signal early exit using two distinct tags:
-- `<PROMISE>NEED_REPLAN</PROMISE>` — current approach is unworkable; loop returns to PLAN with the same goal
-- `<PROMISE>NEED_GOAL_REVISION</PROMISE>` — the goal itself is unreachable; loop stops cleanly for human review. Use this when no approach can work, not just the current one.
-
-**Note**: The `--completion-promise` uses exact string matching and is natively active (no external stop-hook required). It signals Claude's intent to complete; use `--verify` checks for objective verification of that intent.
-
-## Philosophy
-
-Ralph embodies several key principles:
-
-### 1. Iteration > Perfection
-Don't aim for perfect on first try. Let the loop refine the work.
-
-### 2. Failures Are Data
-"Deterministically bad" means failures are predictable and informative. Use them to tune prompts.
-
-### 3. Operator Skill Matters
-Success depends on writing good prompts, not just having a good model.
-
-### 4. Persistence Wins
-Keep trying until success. The loop handles retry logic automatically.
-
-## When to Use Ralph
-
-**Good for:**
-- Well-defined tasks with clear success criteria
-- Tasks requiring iteration and refinement (e.g., getting tests to pass)
-- Greenfield projects where you can walk away
-- Tasks with automatic verification (tests, linters)
-
-**Not good for:**
-- Tasks requiring human judgment or design decisions
-- One-shot operations
-- Tasks with unclear success criteria
-- Production debugging (use targeted debugging instead)
-
-## Real-World Results
-
-- Successfully generated 6 repositories overnight in Y Combinator hackathon testing
-- One $50k contract completed for $297 in API costs
-- Created entire programming language ("cursed") over 3 months using this approach
-
-## Learn More
-
-- Original technique: https://ghuntley.com/ralph/
-- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
-
-## For Help
-
-Run `/help` in Claude Code for detailed command reference and examples.

package/plugins/ralph-wiggum/commands/cancel-ralph.md

@@ -1,18 +0,0 @@
----
-description: "Cancel active Ralph Wiggum loop"
-allowed-tools: ["Bash(test -f .minimal-agent/ralph-loop.local.md:*)", "Bash(rm .minimal-agent/ralph-loop.local.md)", "Read(.minimal-agent/ralph-loop.local.md)"]
-hide-from-slash-command-tool: "true"
----
-
-# Cancel Ralph
-
-To cancel the Ralph loop:
-
-1. Check if `.minimal-agent/ralph-loop.local.md` exists using Bash: `test -f .minimal-agent/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
-
-2. **If NOT_FOUND**: Say "No active Ralph loop found."
-
-3. **If EXISTS**:
-   - Read `.minimal-agent/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
-   - Remove the file using Bash: `rm .minimal-agent/ralph-loop.local.md`
-   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value