opencode-auto-loop 0.1.4 → 0.1.6

package/commands/auto-loop.md

@@ -4,26 +4,30 @@ description: "Start Auto Loop - auto-continues until task completion. Use: /auto
 
 # Auto Loop
 
-Parse `$ARGUMENTS` for the task description and an optional `--max <number>` flag.
+Parse `$ARGUMENTS` for the task description and optional flags:
 
 - If `$ARGUMENTS` contains `--max <number>`, extract that number as **maxIterations** and remove it from the task string.
 - Otherwise, use **maxIterations**: 25
+- If `$ARGUMENTS` contains `--ralph`, set **forceLoop** to `true` and remove it from the task string. Force mode ignores all completion signals and runs for the full maxIterations.
 
 Invoke the `auto-loop` tool with:
 
 - **task**: the extracted task description
 - **maxIterations**: the extracted or default value
+- **forceLoop**: `true` if `--ralph` was present, omit otherwise
 
 Examples:
 - `/auto-loop Build a REST API` → task="Build a REST API", maxIterations=25
 - `/auto-loop Build a REST API --max 50` → task="Build a REST API", maxIterations=50
 - `/auto-loop --max 10 Fix all lint errors` → task="Fix all lint errors", maxIterations=10
+- `/auto-loop --ralph Fix all lint errors` → task="Fix all lint errors", maxIterations=25, forceLoop=true
+- `/auto-loop --ralph --max 10 Fix all lint errors` → task="Fix all lint errors", maxIterations=10, forceLoop=true
 
 After the tool confirms the loop is active, **immediately begin working on the task**. Do not just acknowledge — start doing the work right away.
 
 ## Progress Tracking
 
-Before going idle, you MUST output structured progress so the plugin knows where you left off:
+Before going idle, you MUST output structured progress AND a status line so the plugin knows where you left off:
 
 ```markdown
 ## Completed
@@ -31,15 +35,25 @@ Before going idle, you MUST output structured progress so the plugin knows where
 
 ## Next Steps
 - [ ] What needs to be done next (in priority order)
+
+STATUS: IN_PROGRESS
 ```
 
 ## Completion
 
-When the task is FULLY completed, signal completion by outputting the promise-DONE XML tag on its own line:
+When the task is FULLY completed with NO remaining next steps, signal completion:
+
+```
+STATUS: COMPLETE
 
 <promise>DONE</promise>
+```
 
-**IMPORTANT:** ONLY output this when the task is COMPLETELY and VERIFIABLY finished. Do NOT output false promises to escape the loop.
+**IMPORTANT:**
+- ONLY output `STATUS: COMPLETE` and the DONE signal when the task is COMPLETELY and VERIFIABLY finished.
+- Do NOT output the DONE signal if there are ANY unchecked items (`- [ ]`) in your Next Steps — the plugin WILL reject it.
+- If `STATUS: IN_PROGRESS` is present alongside a DONE signal, the plugin will reject it.
+- Do NOT output false promises to escape the loop.
 
 ## Cancellation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-auto-loop",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Auto-continue for OpenCode",
   "main": "src/index.ts",
   "type": "module",

package/skills/auto-loop/SKILL.md

@@ -27,7 +27,7 @@ After the tool confirms the loop is active, **immediately begin working on the t
 
 ## Progress Tracking - CRITICAL
 
-**Before going idle at the end of each work session, you MUST output structured progress sections.** The plugin parses these to persist your TODOs across iterations so you know exactly where to pick up.
+**Before going idle at the end of each work session, you MUST output structured progress sections AND a status line.** The plugin parses these to persist your TODOs across iterations so you know exactly where to pick up.
 
 Use this format in your final message of each iteration:
 
@@ -41,6 +41,8 @@ Use this format in your final message of each iteration:
 - [ ] Add JWT authentication middleware
 - [ ] Create registration endpoint
 - [ ] Write integration tests
+
+STATUS: IN_PROGRESS
 ```
 
 **Rules:**
@@ -48,6 +50,7 @@ Use this format in your final message of each iteration:
 - Be specific — each item should be a concrete, actionable step
 - Only list truly completed items under ## Completed
 - Order ## Next Steps by priority — the continuation will tell you to start from the top
+- You MUST include a `STATUS: IN_PROGRESS` or `STATUS: COMPLETE` line on its own line in EVERY response
 - The plugin extracts these sections and writes them into `auto-loop.local.md` for the next iteration
 
 ## Completion Signal - CRITICAL RULES
@@ -55,22 +58,36 @@ Use this format in your final message of each iteration:
 When you have FULLY completed the task, signal completion by outputting the promise-DONE XML tag on its own line:
 
 ```
+STATUS: COMPLETE
+
 <promise>DONE</promise>
 ```
 
 **IMPORTANT CONSTRAINTS:**
 
+- **If your Next Steps list has ANY unchecked items (`- [ ]`), you MUST NOT output the DONE signal.** The plugin will detect the contradiction and REJECT the completion, forcing another iteration.
+- You MUST output `STATUS: COMPLETE` (on its own line) alongside the DONE signal. If the plugin detects `STATUS: IN_PROGRESS` with a DONE signal, it will reject the completion.
 - ONLY output the completion signal when the task is COMPLETELY and VERIFIABLY finished
 - The completion tag MUST be on its own line (not inline with other text)
 - Do NOT mention or echo the completion tag in explanatory text — only output it as the actual signal
 - Do NOT output false completion signals to escape the loop, even if you think you're stuck
-- If you're blocked, explain the blocker and request help instead of falsely completing
+- If you're blocked, output `STATUS: IN_PROGRESS` and explain the blocker instead of falsely completing
 
 The loop can only be stopped by:
 1. Truthful completion signal
 2. Max iterations reached
 3. User running `/cancel-auto-loop`
 
+## Force Mode (--ralph)
+
+When started with `--ralph`, the loop ignores ALL completion signals (`<promise>DONE</promise>`, `STATUS: COMPLETE`) and runs for the full iteration count. In force mode:
+- You do NOT need to output `STATUS:` lines or the DONE signal
+- The loop will continue for all iterations regardless
+- Focus on making steady progress each iteration
+- Still output `## Completed` and `## Next Steps` sections so the plugin can track progress
+
+Example: `/auto-loop --ralph --max 10 Continue the refactoring task`
+
 ## Checking Status
 
 Check current iteration and progress:

package/skills/auto-loop-help/SKILL.md

@@ -19,6 +19,15 @@ Example:
 
 The AI will work on your task and automatically continue until completion.
 
+### `/auto-loop <task> --ralph`
+Force mode: ignore all completion signals and run for the full iteration count. Useful when you got interrupted and want to resume, or when you want the AI to keep iterating without stopping early.
+
+Examples:
+```
+/auto-loop --ralph Continue the refactoring
+/auto-loop --ralph --max 10 Fix all lint errors
+```
+
 ### `/cancel-auto-loop`
 Cancel an active Auto Loop before it completes.
 

package/src/index.ts

@@ -16,6 +16,7 @@ interface LoopState {
   iteration: number;
   maxIterations: number;
   debounceMs: number;
+  forceLoop?: boolean;
   sessionId?: string;
   prompt?: string;
   completed?: string;
@@ -31,6 +32,8 @@ const SERVICE_NAME = "auto-loop";
 const STATE_FILENAME = "auto-loop.local.md";
 const OPENCODE_CONFIG_DIR = join(homedir(), ".config/opencode");
 const COMPLETION_TAG = /^\s*<promise>\s*DONE\s*<\/promise>\s*$/im;
+const STATUS_COMPLETE_TAG = /^\s*STATUS:\s*COMPLETE\s*$/im;
+const STATUS_IN_PROGRESS_TAG = /^\s*STATUS:\s*IN_PROGRESS\s*$/im;
 const DEFAULT_DEBOUNCE_MS = 2000;
 const DEFAULT_MAX_ITERATIONS = 25;
 
@@ -122,6 +125,7 @@ function parseState(content: string): LoopState {
     if (key === "iteration") state.iteration = parseInt(value) || 0;
     if (key === "maxIterations") state.maxIterations = parseInt(value) || DEFAULT_MAX_ITERATIONS;
     if (key === "debounceMs") state.debounceMs = parseInt(value) || DEFAULT_DEBOUNCE_MS;
+    if (key === "forceLoop") state.forceLoop = value === "true";
     if (key === "sessionId") state.sessionId = value || undefined;
   }
 
@@ -157,6 +161,7 @@ function serializeState(state: LoopState): string {
     `maxIterations: ${state.maxIterations}`,
     `debounceMs: ${state.debounceMs}`,
   ];
+  if (state.forceLoop) lines.push(`forceLoop: ${state.forceLoop}`);
   if (state.sessionId) lines.push(`sessionId: ${state.sessionId}`);
   lines.push("---");
   if (state.prompt) lines.push("", state.prompt);
@@ -247,6 +252,65 @@ function checkCompletion(text: string): boolean {
   return COMPLETION_TAG.test(stripCodeFences(text));
 }
 
+// Extract the STATUS signal presence from text.
+function getStatusSignals(text: string): {
+  hasComplete: boolean;
+  hasInProgress: boolean;
+} {
+  const cleaned = stripCodeFences(text);
+  return {
+    hasComplete: STATUS_COMPLETE_TAG.test(cleaned),
+    hasInProgress: STATUS_IN_PROGRESS_TAG.test(cleaned),
+  };
+}
+
+// Check if the parsed Next Steps section contains unchecked items (- [ ] ...).
+// Returns true if there are incomplete items, meaning the task is NOT done.
+function hasIncompleteSteps(text: string): boolean {
+  const nextSteps = extractNextSteps(stripCodeFences(text));
+  if (!nextSteps) return false;
+
+  const uncheckedItems = nextSteps
+    .split("\n")
+    .filter((line) => /^\s*-\s*\[ \]/.test(line));
+
+  return uncheckedItems.length > 0;
+}
+
+// Validate whether the DONE signal should be honored.
+// Returns { valid: true } if completion is legitimate,
+// or { valid: false, reason: string } if it should be rejected.
+function validateCompletion(text: string): { valid: boolean; reason?: string } {
+  // Check 1: contradictory STATUS signals
+  const statusSignals = getStatusSignals(text);
+  if (statusSignals.hasComplete && statusSignals.hasInProgress) {
+    return {
+      valid: false,
+      reason: "Both STATUS: COMPLETE and STATUS: IN_PROGRESS are present",
+    };
+  }
+
+  // Check 2: STATUS signal contradicts DONE
+  if (statusSignals.hasInProgress) {
+    return {
+      valid: false,
+      reason: "STATUS: IN_PROGRESS contradicts the DONE signal",
+    };
+  }
+
+  // Check 3: Unchecked next steps exist
+  if (hasIncompleteSteps(text)) {
+    return {
+      valid: false,
+      reason: "Unchecked next steps (- [ ] ...) found alongside DONE signal",
+    };
+  }
+
+  // Check 4: If STATUS signal is present and is COMPLETE, extra confidence
+  // If no STATUS signal at all, still allow (backward compatibility)
+  return { valid: true };
+}
+
 // Extract next steps / TODOs from assistant message text
 // Looks for common patterns: ## Next Steps, ## TODO, checkbox lists, numbered lists after keywords
 function extractNextSteps(text: string): string | undefined {
@@ -351,13 +415,24 @@ function buildProgressSection(state: LoopState): string {
 // Build the loop context reminder for post-compaction injection
 function buildLoopContextReminder(state: LoopState): string {
   const progress = buildProgressSection(state);
-  return `[AUTO LOOP ACTIVE — Iteration ${state.iteration}/${state.maxIterations}]
+  const forceLabel = state.forceLoop ? " [FORCE MODE]" : "";
+  const rules = state.forceLoop
+    ? `IMPORTANT RULES:
+- Before going idle, output ## Completed and ## Next Steps sections
+- FORCE MODE is active — the loop will continue for all ${state.maxIterations} iterations regardless of completion signals
+- Focus on making steady progress each iteration`
+    : `IMPORTANT RULES:
+- Before going idle, output ## Completed and ## Next Steps sections
+- You MUST include a STATUS line: either \`STATUS: IN_PROGRESS\` or \`STATUS: COMPLETE\` on its own line
+- Do NOT output <promise>DONE</promise> if there are ANY unchecked items (\`- [ ]\`) in your Next Steps — the plugin WILL reject it
+- Only output \`STATUS: COMPLETE\` and the DONE signal when ALL steps are truly finished and Next Steps is empty
+- Do NOT output false completion promises. If blocked, output \`STATUS: IN_PROGRESS\` and explain the blocker.`;
+
+  return `[AUTO LOOP${forceLabel} ACTIVE — Iteration ${state.iteration}/${state.maxIterations}]
 
 Original task: ${state.prompt || "(no task specified)"}
 ${progress}
-When the task is FULLY complete, you MUST output: <promise>DONE</promise>
-Before going idle, list your progress using ## Completed and ## Next Steps sections.
-Do NOT output false completion promises. If blocked, explain the blocker.`;
+${rules}`;
 }
 
 // Check if session is currently busy (not idle)
@@ -440,8 +515,12 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
             .number()
             .optional()
             .describe("Debounce delay between iterations in ms (default: 2000)"),
+          forceLoop: tool.schema
+            .boolean()
+            .optional()
+            .describe("Force mode (--ralph): ignore completion signals and run for all iterations"),
         },
-        async execute({ task, maxIterations = DEFAULT_MAX_ITERATIONS, debounceMs = DEFAULT_DEBOUNCE_MS }, context) {
+        async execute({ task, maxIterations = DEFAULT_MAX_ITERATIONS, debounceMs = DEFAULT_DEBOUNCE_MS, forceLoop = false }, context) {
           if (context.abort.aborted) return "Auto Loop start was cancelled.";
 
           const state: LoopState = {
@@ -449,6 +528,7 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
             iteration: 0,
             maxIterations,
             debounceMs,
+            forceLoop: forceLoop ? true : undefined,
             sessionId: context.sessionID,
             prompt: task,
           };
@@ -457,16 +537,21 @@ export const AutoLoopPlugin: Plugin = async (ctx) => {
           continuationInFlight = false;
           lastContinuation = 0;
 
-          log("info", `Loop started for session ${context.sessionID}`);
-          toast(`Auto Loop started (max ${maxIterations} iterations)`, "success");
+          const modeLabel = forceLoop ? " [FORCE MODE]" : "";
+          log("info", `Loop started${modeLabel} for session ${context.sessionID}`);
+          toast(`Auto Loop started${modeLabel} (max ${maxIterations} iterations)`, "success");
+
+          const forceNote = forceLoop
+            ? `\n\n**FORCE MODE (--ralph):** Completion signals are IGNORED. The loop will run for all ${maxIterations} iterations regardless. Focus on making progress each iteration — you do NOT need to output STATUS or DONE signals.`
+            : "";
 
-          return `Auto Loop started (max ${maxIterations} iterations).
+          return `Auto Loop started (max ${maxIterations} iterations).${forceNote}
 
 Task: ${task}
 
-**Begin working on the task now.** The loop will auto-continue until you signal completion.
+**Begin working on the task now.** The loop will auto-continue until ${forceLoop ? `all ${maxIterations} iterations are used` : "you signal completion"}.
 
-Before going idle each iteration, output structured progress:
+Before going idle each iteration, output structured progress${forceLoop ? "" : " AND a status line"}:
 
 \`\`\`
 ## Completed
@@ -474,10 +559,18 @@ Before going idle each iteration, output structured progress:
 
 ## Next Steps
 - [ ] What remains (in priority order)
+${forceLoop ? "" : "\nSTATUS: IN_PROGRESS"}
 \`\`\`
-
-When the task is FULLY and VERIFIABLY complete, output the completion signal on its own line (the promise-DONE XML tag). Do NOT mention or echo the completion tag until you are truly done.
-
+${forceLoop ? "" : `
+## Completion Rules — READ CAREFULLY
+
+1. **If your Next Steps list has ANY unchecked items (\`- [ ]\`), you MUST NOT output the DONE signal.** The plugin will reject it.
+2. You MUST include a \`STATUS: COMPLETE\` or \`STATUS: IN_PROGRESS\` line on its own line in every response.
+3. Only when ALL steps are done and Next Steps is empty, output:
+   - \`STATUS: COMPLETE\` on its own line
+   - The promise-DONE XML tag on its own line
+4. If you are blocked or stuck, output \`STATUS: IN_PROGRESS\` and explain the blocker. Do NOT output a false DONE.
+`}
 Use /cancel-auto-loop to stop early.`;
         },
       }),
@@ -512,6 +605,8 @@ Use /cancel-auto-loop to stop early.`;
 
 - \`/auto-loop <task>\` - Start an auto-continuation loop (default: 25 iterations)
 - \`/auto-loop <task> --max <n>\` - Start with a custom iteration limit
+- \`/auto-loop <task> --ralph\` - Force mode: ignore completion signals, run all iterations
+- \`/auto-loop <task> --ralph --max <n>\` - Force mode with custom limit
 - \`/cancel-auto-loop\` - Stop an active loop
 - \`/auto-loop-help\` - Show this help
 
@@ -519,6 +614,8 @@ Use /cancel-auto-loop to stop early.`;
 
 - \`/auto-loop Build a REST API\` — runs up to 25 iterations
 - \`/auto-loop Fix all lint errors --max 10\` — runs up to 10 iterations
+- \`/auto-loop --ralph Continue refactoring\` — force runs all 25 iterations, ignores DONE signals
+- \`/auto-loop --ralph --max 50 Big migration\` — force runs all 50 iterations
 
 ## How It Works
 
@@ -527,6 +624,13 @@ Use /cancel-auto-loop to stop early.`;
 3. Plugin auto-continues if not complete
 4. Loop stops when AI outputs: <promise>DONE</promise>
 
+## Force Mode (--ralph)
+
+When \`--ralph\` is used, the loop ignores ALL completion signals and runs for the full iteration count. Useful when:
+- You got interrupted and want to continue no matter what
+- You want the AI to keep iterating and improving
+- You don't want the AI to stop early
+
 ## State File
 
 Located at: .opencode/auto-loop.local.md`;
@@ -559,12 +663,23 @@ Located at: .opencode/auto-loop.local.md`;
         const lastText = await getLastAssistantText(client, sessionId, directory, log);
 
         // Skip completion check on iteration 0 (first idle after loop start)
-        // to avoid false positives from the tool's initial response text
-        if (state.iteration > 0 && lastText && checkCompletion(lastText)) {
-          await clearState(directory, log);
-          log("info", `Loop completed at iteration ${state.iteration}`);
-          toast(`Auto Loop completed after ${state.iteration} iteration(s)`, "success");
-          return;
+        // to avoid false positives from the tool's initial response text.
+        // Also skip entirely when forceLoop is true — force mode ignores
+        // all completion signals and runs until max iterations.
+        if (!state.forceLoop && state.iteration > 0 && lastText && checkCompletion(lastText)) {
+          // Validate the DONE signal — reject if there are unchecked steps
+          // or if the STATUS signal contradicts completion
+          const validation = validateCompletion(lastText);
+          if (validation.valid) {
+            await clearState(directory, log);
+            log("info", `Loop completed at iteration ${state.iteration}`);
+            toast(`Auto Loop completed after ${state.iteration} iteration(s)`, "success");
+            return;
+          } else {
+            log("warn", `Rejected premature DONE signal: ${validation.reason}`);
+            toast(`Auto Loop: DONE rejected — ${validation.reason}`, "warning");
+            // Fall through to send another continuation prompt
+          }
         }
 
         if (state.iteration >= state.maxIterations) {
@@ -591,15 +706,26 @@ Located at: .opencode/auto-loop.local.md`;
         // Build continuation prompt with progress context
         const progressSection = buildProgressSection(newState);
 
-        const continuationPrompt = `[AUTO LOOP — ITERATION ${newState.iteration}/${newState.maxIterations}]
+        const forceLabel = state.forceLoop ? " [FORCE MODE]" : "";
+        const importantRules = state.forceLoop
+          ? `IMPORTANT:
+- Pick up from the next incomplete step below
+- Before going idle, list your progress using ## Completed and ## Next Steps sections
+- FORCE MODE is active — the loop will continue for all ${newState.maxIterations} iterations regardless of completion signals
+- Focus on making steady progress each iteration`
+          : `IMPORTANT:
+- Pick up from the next incomplete step below
+- Before going idle, list your progress using ## Completed and ## Next Steps sections
+- You MUST include a STATUS line: either \`STATUS: IN_PROGRESS\` or \`STATUS: COMPLETE\` on its own line
+- Do NOT output <promise>DONE</promise> if there are ANY unchecked items (\`- [ ]\`) in your Next Steps — the plugin WILL reject it
+- Only output \`STATUS: COMPLETE\` and the DONE signal when ALL steps are truly finished and Next Steps is empty
+- Do not stop until the task is truly done`;
+
+        const continuationPrompt = `[AUTO LOOP${forceLabel} — ITERATION ${newState.iteration}/${newState.maxIterations}]
 
 Continue working on the task. Do NOT repeat work that is already done.
 ${progressSection}
-IMPORTANT:
-- Pick up from the next incomplete step below
-- When FULLY complete, output: <promise>DONE</promise>
-- Before going idle, list your progress using ## Completed and ## Next Steps sections
-- Do not stop until the task is truly done
+${importantRules}
 
 Original task:
 ${state.prompt || "(no task specified)"}`;