@entelligentsia/pi-ralph 1.0.0

package/README.md

@@ -0,0 +1,147 @@
+# pi-ralph
+
+**A [pi](https://github.com/earendil-works/pi) extension** — iterative goal-achievement loop with Generator → Critique → Judge agents.
+
+[![npm](https://img.shields.io/npm/v/@entelligentsia/pi-ralph?style=flat-square)](https://www.npmjs.com/package/@entelligentsia/pi-ralph)
+
+## Install
+
+```
+pi install npm:@entelligentsia/pi-ralph
+```
+
+Or pin a version:
+
+```
+pi install npm:@entelligentsia/pi-ralph@1.0.0
+```
+
+From GitHub:
+
+```
+pi install git:github.com:Entelligentsia/pi-ralph
+```
+
+## What It Does
+
+Give it a goal. It loops — generate, critique, judge — until the goal is met or iterations run out.
+
+Each agent's system prompt is dynamically generated from the goal, so they're domain-aligned from the start. Output streams to chat as it happens — like `tail -f`.
+
+## Usage
+
+```
+/ralph-loop-anything --goal "Your goal here" --loop 5
+```
+
+- `--goal` (required): The goal to achieve
+- `--loop` (optional, default 3): Maximum iterations
+
+## How It Works
+
+```
+1. Feasibility check  →  can an LLM do this?
+2. Prompt generation   →  domain + agent prompts tailored to the goal
+3. Loop (up to N):
+   ├─ Generate   →  produces a result
+   ├─ Critique   →  identifies problems, suggests improvements
+   └─ Judge      →  { done: true/false, reason }
+       └── if not done: feeds result + criticism back to Generator
+4. Final message with verdict
+```
+
+Every step posts a message to chat as it completes. No hidden progress bars — you see each agent's output the moment it arrives.
+
+### LLM Calls Per Run
+
+| Step | Calls |
+|------|-------|
+| Feasibility | 1 |
+| Prompt generation | 1 |
+| Per loop iteration | 3 (generate + critique + judge) |
+
+Total for `--loop 3`: 1 + 1 + (3 × 3) = **11** LLM calls
+
+## Examples
+
+### Creative Writing
+
+```
+/ralph-loop-anything --goal "Write a complete short story in one sentence and fewer than 10 words that is better than Hemingway could write"
+```
+
+```
+/ralph-loop-anything --goal "Write a villanelle poem about debugging at 3am"
+```
+
+```
+/ralph-loop-anything --goal "Invent a new myth that explains why rivers bend, told as if by a 9th-century monk"
+```
+
+### Code
+
+```
+/ralph-loop-anything --goal "Write an ergonomic CLI argument parser in Rust that handles flags, options, subcommands, and generates help text" --loop 5
+```
+
+```
+/ralph-loop-anything --goal "Implement a lock-free concurrent hash map in Zig"
+```
+
+```
+/ralph-loop-anything --goal "Write a single-file SQLite clone in C that supports CREATE TABLE, INSERT, and SELECT with WHERE clauses"
+```
+
+### Design & Strategy
+
+```
+/ralph-loop-anything --goal "Design a go-to-market strategy for a developer tools startup that has a free CLI tool but wants to monetize a team tier"
+```
+
+```
+/ralph-loop-anything --goal "Create a 12-week fitness program for a 40-year-old desk worker who has 30 minutes a day and bad knees"
+```
+
+```
+/ralph-loop-anything --goal "Write a production-ready incident response playbook for a SaaS company experiencing a data breach"
+```
+
+### Explaining & Teaching
+
+```
+/ralph-loop-anything --goal "Explain monads to a JavaScript developer who has never used Haskell, using only analogies from web development"
+```
+
+```
+/ralph-loop-anything --goal "Create a 5-minute presentation script that explains neural networks to a room of skeptical middle managers"
+```
+
+### Constraints & Style
+
+```
+/ralph-loop-anything --goal "Rewrite the Gettysburg Address as if it were a Slack announcement from a tech CEO" --loop 2
+```
+
+```
+/ralph-loop-anything --goal "Write a recipe for coq au vin where every step is a haiku"
+```
+
+```
+/ralph-loop-anything --goal "Explain quantum entanglement using only words with 4 letters or fewer"
+```
+
+## Architecture
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Thin entry point — parses args, calls orchestrator |
+| `agents/orchestrator.ts` | Coordinates full flow: feasibility, prompts, loop, verdict |
+| `agents/generator.ts` | Generator agent — produces or improves a result |
+| `agents/critique.ts` | Critique agent — evaluates result against the goal |
+| `agents/judge.ts` | Judge agent — decides if goal is achieved |
+| `types.ts` | Shared interfaces (`LoopIteration`, `LoopStep`, etc.) |
+| `prompts.ts` | Static system prompts (feasibility, prompt generator, fallbacks) |
+| `helpers.ts` | Text utilities (`truncate`, `firstNLines`) |
+| `llm.ts` | LLM client (`oneshotLLM`, `parseJsonResponse`) |
+| `argParser.ts` | Command argument parsing |
+| `renderer.ts` | Message renderer — passes markdown content through |

package/agents/critique.ts

@@ -0,0 +1,77 @@
+// ============================================================================
+// Critique Agent
+//
+// Evaluates a result against the goal.
+// Identifies problems, gaps, and suggests concrete improvements.
+// ============================================================================
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { oneshotLLM } from "../llm";
+import { FALLBACK_CRITIQUE_PROMPT } from "../prompts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CritiqueInput {
+	goal: string;
+	systemPrompt: string;
+	result: string;
+}
+
+export interface CritiqueResult {
+	text: string;
+	error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export async function execute(
+	ctx: ExtensionCommandContext,
+	input: CritiqueInput,
+	signal?: AbortSignal,
+): Promise<CritiqueResult> {
+	const userMsg = buildUserMessage(input);
+	const systemPrompt = input.systemPrompt || FALLBACK_CRITIQUE_PROMPT;
+
+	const result = await oneshotLLM(ctx, systemPrompt, userMsg, signal);
+
+	if (result.error) {
+		return { text: "", error: result.error };
+	}
+
+	return { text: result.text };
+}
+
+// ---------------------------------------------------------------------------
+// Message Construction
+// ---------------------------------------------------------------------------
+
+function buildUserMessage(input: CritiqueInput): string {
+	return [
+		`Goal: ${input.goal}`,
+		``,
+		`Result to evaluate:`,
+		`${input.result}`,
+		``,
+		`Critically evaluate this result against the goal. Identify problems and suggest improvements.`,
+	].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Chat Message Formatting
+// ---------------------------------------------------------------------------
+
+export function formatBefore(loop: number, maxLoops: number): string {
+	return `## Loop ${loop}/${maxLoops} — Critiquing...`;
+}
+
+export function formatAfter(loop: number, maxLoops: number, text: string): string {
+	return `## Loop ${loop}/${maxLoops} — Critique\n\n${text}`;
+}
+
+export function formatError(loop: number, maxLoops: number, error: string): string {
+	return `## Loop ${loop}/${maxLoops} — Critique failed\n\n${error}`;
+}

package/agents/generator.ts

@@ -0,0 +1,88 @@
+// ============================================================================
+// Generator Agent
+//
+// Produces or improves a result for the goal.
+// On first run: works from the goal alone.
+// On revision: receives previous result + criticism and improves.
+// ============================================================================
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { oneshotLLM } from "../llm";
+import { FALLBACK_GENERATOR_PROMPT } from "../prompts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface GeneratorInput {
+	goal: string;
+	systemPrompt: string;
+	/** Previous result to improve (undefined on first run) */
+	previousResult?: string;
+	/** Criticism of previous result (undefined on first run) */
+	previousCriticism?: string;
+}
+
+export interface GeneratorResult {
+	text: string;
+	error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export async function execute(
+	ctx: ExtensionCommandContext,
+	input: GeneratorInput,
+	signal?: AbortSignal,
+): Promise<GeneratorResult> {
+	const userMsg = buildUserMessage(input);
+	const systemPrompt = input.systemPrompt || FALLBACK_GENERATOR_PROMPT;
+
+	const result = await oneshotLLM(ctx, systemPrompt, userMsg, signal);
+
+	if (result.error) {
+		return { text: "", error: result.error };
+	}
+
+	return { text: result.text };
+}
+
+// ---------------------------------------------------------------------------
+// Message Construction
+// ---------------------------------------------------------------------------
+
+function buildUserMessage(input: GeneratorInput): string {
+	if (!input.previousResult) {
+		return `Goal: ${input.goal}\n\nProduce your best result to achieve this goal.`;
+	}
+
+	return [
+		`Goal: ${input.goal}`,
+		``,
+		`Previous result:`,
+		`${input.previousResult}`,
+		``,
+		`Criticism of the previous result:`,
+		`${input.previousCriticism || "(none)"}`,
+		``,
+		`Improve upon the previous result, carefully addressing all the criticisms. Produce a better version.`,
+	].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Chat Message Formatting
+// ---------------------------------------------------------------------------
+
+export function formatBefore(loop: number, maxLoops: number): string {
+	return `## Loop ${loop}/${maxLoops} — Generating...`;
+}
+
+export function formatAfter(loop: number, maxLoops: number, text: string): string {
+	return `## Loop ${loop}/${maxLoops} — Generated\n\n${text}`;
+}
+
+export function formatError(loop: number, maxLoops: number, error: string): string {
+	return `## Loop ${loop}/${maxLoops} — Generator failed\n\n${error}`;
+}

package/agents/judge.ts

@@ -0,0 +1,95 @@
+// ============================================================================
+// Judge Agent
+//
+// Determines if a result adequately achieves the goal, given the criticism.
+// Returns structured verdict: { done: boolean, reason: string }.
+// ============================================================================
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { oneshotLLM, parseJsonResponse } from "../llm";
+import { FALLBACK_JUDGE_PROMPT } from "../prompts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface JudgeInput {
+	goal: string;
+	systemPrompt: string;
+	result: string;
+	criticism: string;
+}
+
+export interface JudgeResult {
+	done: boolean;
+	reason: string;
+	raw: string;
+	error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export async function execute(
+	ctx: ExtensionCommandContext,
+	input: JudgeInput,
+	signal?: AbortSignal,
+): Promise<JudgeResult> {
+	const userMsg = buildUserMessage(input);
+	const systemPrompt = input.systemPrompt || FALLBACK_JUDGE_PROMPT;
+
+	const result = await oneshotLLM(ctx, systemPrompt, userMsg, signal);
+
+	if (result.error) {
+		return { done: false, reason: "", raw: "", error: result.error };
+	}
+
+	const parsed = parseJsonResponse<{ done?: boolean; reason?: string }>(result.text);
+	let done = false;
+	let reason = "";
+
+	if (parsed) {
+		done = parsed.done === true;
+		reason = parsed.reason || "";
+	} else {
+		reason = `(could not parse judge response) ${result.text.slice(0, 200)}`;
+	}
+
+	return { done, reason, raw: result.text };
+}
+
+// ---------------------------------------------------------------------------
+// Message Construction
+// ---------------------------------------------------------------------------
+
+function buildUserMessage(input: JudgeInput): string {
+	return [
+		`Goal: ${input.goal}`,
+		``,
+		`Result:`,
+		`${input.result}`,
+		``,
+		`Criticism:`,
+		`${input.criticism}`,
+		``,
+		`Determine if the goal has been adequately achieved. Respond with JSON.`,
+	].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Chat Message Formatting
+// ---------------------------------------------------------------------------
+
+export function formatBefore(loop: number, maxLoops: number): string {
+	return `## Loop ${loop}/${maxLoops} — Judging...`;
+}
+
+export function formatAfter(loop: number, maxLoops: number, done: boolean, reason: string): string {
+	const verdict = done ? "DONE ✓" : "CONTINUE ✗";
+	return `## Loop ${loop}/${maxLoops} — Judge: ${verdict}\n\n${reason}`;
+}
+
+export function formatError(loop: number, maxLoops: number, error: string): string {
+	return `## Loop ${loop}/${maxLoops} — Judge failed\n\n${error}`;
+}

package/agents/orchestrator.ts

@@ -0,0 +1,293 @@
+// ============================================================================
+// Orchestrator Agent
+//
+// Coordinates the full ralph-loop flow:
+//   1. Feasibility check
+//   2. Domain identification + agent prompt generation
+//   3. Loop: Generator → Critique → Judge (repeat until done or max loops)
+//   4. Final verdict
+//
+// Every step posts a message to chat as it completes — tail -f style.
+// ============================================================================
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { oneshotLLM, parseJsonResponse } from "../llm";
+import { FEASIBILITY_PROMPT, PROMPT_GENERATOR_PROMPT, FALLBACK_GENERATOR_PROMPT, FALLBACK_CRITIQUE_PROMPT, FALLBACK_JUDGE_PROMPT } from "../prompts";
+import { truncate } from "../helpers";
+import * as Generator from "./generator";
+import * as Critique from "./critique";
+import * as Judge from "./judge";
+import type { AgentPrompts, RalphLoopResult, LoopIteration } from "../types";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface OrchestratorInput {
+	goal: string;
+	maxLoops: number;
+}
+
+export interface OrchestratorResult {
+	details: RalphLoopResult;
+	achieved: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Execution
+// ---------------------------------------------------------------------------
+
+export async function execute(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	input: OrchestratorInput,
+): Promise<OrchestratorResult | null> {
+	const { goal, maxLoops } = input;
+	const signal = ctx.signal;
+
+	// ── Step 1: Feasibility ──────────────────────────────────────────
+	send(pi, `## Checking feasibility\n\n> ${goal}\n\nEvaluating whether this goal is achievable with an LLM...`);
+
+	const feasibilityPrompt = `Evaluate whether this goal is achievable using an LLM: "${goal}"`;
+	const feasibility = await oneshotLLM(ctx, FEASIBILITY_PROMPT, feasibilityPrompt, signal);
+
+	if (feasibility.error) {
+		send(pi, `## Feasibility check failed\n\n${feasibility.error}`);
+		return null;
+	}
+
+	const feasibilityJson = parseJsonResponse<{ achievable?: boolean; reason?: string }>(feasibility.text);
+	let feasible = true;
+	let feasibilityReason = "";
+
+	if (feasibilityJson) {
+		feasible = feasibilityJson.achievable !== false;
+		feasibilityReason = feasibilityJson.reason || "";
+	} else {
+		feasibilityReason = "Could not parse feasibility response; proceeding anyway";
+	}
+
+	if (!feasible) {
+		send(pi, `## Goal not achievable\n\n${feasibilityReason || feasibility.text.slice(0, 500)}`);
+		return null;
+	}
+
+	send(pi, `## Feasibility: Yes\n\n${feasibilityReason}\n\nGenerating agent prompts...`);
+
+	// ── Step 2: Generate agent prompts ───────────────────────────────
+	const promptGenResult = await generateAgentPrompts(ctx, goal, signal);
+
+	let agentPrompts: AgentPrompts;
+	let domain: string;
+
+	if (promptGenResult) {
+		agentPrompts = promptGenResult.prompts;
+		domain = promptGenResult.domain;
+		send(pi, formatPromptsMessage(domain, agentPrompts));
+	} else {
+		agentPrompts = {
+			generator_prompt: FALLBACK_GENERATOR_PROMPT,
+			critique_prompt: FALLBACK_CRITIQUE_PROMPT,
+			judge_prompt: FALLBACK_JUDGE_PROMPT,
+		};
+		domain = "General";
+	}
+
+	// ── Step 3: Ralph Loop ───────────────────────────────────────────
+	const iterations: LoopIteration[] = [];
+	let currentResult = "";
+	let currentCriticism = "";
+
+	for (let i = 1; i <= maxLoops; i++) {
+		const iteration = buildIteration(i);
+
+		// ── Generate ──
+		send(pi, Generator.formatBefore(i, maxLoops));
+		const genResult = await Generator.execute(ctx, {
+			goal,
+			systemPrompt: agentPrompts.generator_prompt,
+			previousResult: i > 1 ? currentResult : undefined,
+			previousCriticism: i > 1 ? currentCriticism : undefined,
+		}, signal);
+
+		if (genResult.error) {
+			send(pi, Generator.formatError(i, maxLoops, genResult.error));
+			return null;
+		}
+
+		currentResult = genResult.text;
+		iteration.steps.push({ type: "generate", preview: truncate(currentResult, 100), full: currentResult });
+		send(pi, Generator.formatAfter(i, maxLoops, currentResult));
+
+		// ── Critique ──
+		send(pi, Critique.formatBefore(i, maxLoops));
+		const critResult = await Critique.execute(ctx, {
+			goal,
+			systemPrompt: agentPrompts.critique_prompt,
+			result: currentResult,
+		}, signal);
+
+		if (critResult.error) {
+			send(pi, Critique.formatError(i, maxLoops, critResult.error));
+			return null;
+		}
+
+		currentCriticism = critResult.text;
+		iteration.steps.push({ type: "critique", preview: truncate(currentCriticism, 100), full: currentCriticism });
+		send(pi, Critique.formatAfter(i, maxLoops, currentCriticism));
+
+		// ── Judge ──
+		send(pi, Judge.formatBefore(i, maxLoops));
+		const judgeResult = await Judge.execute(ctx, {
+			goal,
+			systemPrompt: agentPrompts.judge_prompt,
+			result: currentResult,
+			criticism: currentCriticism,
+		}, signal);
+
+		if (judgeResult.error) {
+			send(pi, Judge.formatError(i, maxLoops, judgeResult.error));
+			return null;
+		}
+
+		iteration.steps.push({ type: "judge", verdict: judgeResult.done, reason: judgeResult.reason, raw: judgeResult.raw });
+		iteration.achieved = judgeResult.done;
+		iteration.finalResult = currentResult;
+		iteration.finalCriticism = currentCriticism;
+		iteration.finalJudgeReason = judgeResult.reason;
+
+		iterations.push(iteration);
+
+		send(pi, Judge.formatAfter(i, maxLoops, judgeResult.done, judgeResult.reason));
+
+		if (judgeResult.done) break;
+	}
+
+	// ── Step 4: Final verdict ─────────────────────────────────────────
+	const lastIteration = iterations[iterations.length - 1];
+	const achieved = lastIteration?.achieved ?? false;
+	const verdictReason = lastIteration?.finalJudgeReason || "no judgment rendered";
+	const finalLabel = achieved ? "GOAL ACHIEVED ✓" : "GOAL NOT FULLY ACHIEVED ✗";
+
+	const lines: string[] = [];
+	lines.push(`## Result: ${finalLabel}`);
+	lines.push(``);
+	lines.push(`> ${verdictReason}`);
+	lines.push(``);
+	lines.push(`---`);
+	lines.push(``);
+	lines.push(`**Final output:**`);
+	lines.push(``);
+	lines.push(lastIteration?.finalResult || "(no result)");
+
+	if (lastIteration?.finalCriticism && lastIteration.finalCriticism.trim()) {
+		lines.push(``);
+		lines.push(`**Final criticism:**`);
+		lines.push(``);
+		lines.push(lastIteration.finalCriticism);
+	}
+
+	lines.push(``);
+	lines.push(`---`);
+	lines.push(``);
+	lines.push(`*${iterations.length}/${maxLoops} iterations, domain: ${domain}*`);
+
+	const details: RalphLoopResult = {
+		goal,
+		domain,
+		maxLoops,
+		loopCount: iterations.length,
+		achieved,
+		feasibilityReason,
+		feasibilityRaw: feasibility.text,
+		agentPrompts,
+		result: lastIteration?.finalResult || "",
+		criticism: lastIteration?.finalCriticism || "",
+		judgeReason: lastIteration?.finalJudgeReason || "",
+		iterations,
+	};
+
+	send(pi, lines.join("\n"), details);
+
+	return { details, achieved };
+}
+
+// ---------------------------------------------------------------------------
+// Agent Prompt Generation
+// ---------------------------------------------------------------------------
+
+async function generateAgentPrompts(
+	ctx: ExtensionCommandContext,
+	goal: string,
+	signal: AbortSignal | undefined,
+): Promise<{ prompts: AgentPrompts; domain: string } | null> {
+	const userMsg = `Design system prompts for three agents that will work together to achieve this goal:
+
+"${goal}"
+
+Each prompt must be specifically tailored to this goal's domain. Output the JSON with keys: domain, generator_prompt, critique_prompt, judge_prompt. The "domain" field should identify the subject area (e.g., "Literary Fiction", "Systems Programming", "Business Strategy").`;
+
+	const result = await oneshotLLM(ctx, PROMPT_GENERATOR_PROMPT, userMsg, signal);
+
+	if (result.error) return null;
+
+	const json = parseJsonResponse<{ domain?: string; generator_prompt?: string; critique_prompt?: string; judge_prompt?: string }>(result.text);
+
+	if (
+		!json ||
+		typeof json.generator_prompt !== "string" ||
+		typeof json.critique_prompt !== "string" ||
+		typeof json.judge_prompt !== "string"
+	) return null;
+
+	return {
+		prompts: {
+			generator_prompt: json.generator_prompt,
+			critique_prompt: json.critique_prompt,
+			judge_prompt: json.judge_prompt,
+		},
+		domain: json.domain || "General",
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function buildIteration(loop: number): LoopIteration {
+	return {
+		loop,
+		steps: [],
+		achieved: false,
+		finalResult: "",
+		finalCriticism: "",
+		finalJudgeReason: "",
+	};
+}
+
+function send(pi: ExtensionAPI, content: string, details?: RalphLoopResult): void {
+	pi.sendMessage({
+		customType: "ralph-loop",
+		content,
+		display: true,
+		...(details ? { details } : {}),
+	});
+}
+
+function formatPromptsMessage(domain: string, prompts: AgentPrompts): string {
+	return [
+		`## Agent Prompts — Domain: ${domain}`,
+		``,
+		`### Generator`,
+		``,
+		prompts.generator_prompt,
+		``,
+		`### Critique`,
+		``,
+		prompts.critique_prompt,
+		``,
+		`### Judge`,
+		``,
+		prompts.judge_prompt,
+	].join("\n");
+}

package/argParser.ts

@@ -0,0 +1,51 @@
+// ============================================================================
+// Argument Parsing
+// ============================================================================
+
+import type { ParsedArgs } from "./types";
+
+/**
+ * Parse command arguments: --goal "..." [--loop N]
+ * Returns { goal: string, loop: number }
+ * Throws if --goal is missing.
+ */
+export function parseArgs(raw: string): ParsedArgs {
+	let loop = 3;
+
+	const loopMatch = raw.match(/--loop\s+(\d+)/);
+	if (loopMatch) {
+		loop = parseInt(loopMatch[1], 10);
+	}
+
+	let remaining = raw.replace(/--loop\s+\d+/, "").trim();
+
+	if (remaining.startsWith("--goal")) {
+		remaining = remaining.slice(6).trim();
+	}
+
+	let goal = "";
+
+	if (remaining.startsWith('"')) {
+		const endQuote = remaining.indexOf('"', 1);
+		if (endQuote !== -1) {
+			goal = remaining.slice(1, endQuote);
+		} else {
+			goal = remaining.slice(1);
+		}
+	} else if (remaining.startsWith("'")) {
+		const endQuote = remaining.indexOf("'", 1);
+		if (endQuote !== -1) {
+			goal = remaining.slice(1, endQuote);
+		} else {
+			goal = remaining.slice(1);
+		}
+	} else {
+		goal = remaining;
+	}
+
+	if (!goal.trim()) {
+		throw new Error('--goal is required. Usage: /ralph-loop-anything --goal "Your goal" [--loop N]');
+	}
+
+	return { goal: goal.trim(), loop };
+}

package/helpers.ts

@@ -0,0 +1,19 @@
+// ============================================================================
+// Text Helpers
+// ============================================================================
+
+/**
+ * Truncate text to maxLen characters, appending "…" if truncated
+ */
+export function truncate(text: string, maxLen: number): string {
+	if (text.length <= maxLen) return text;
+	return text.slice(0, maxLen) + "…";
+}
+
+/**
+ * Return only the first n lines of text
+ */
+export function firstNLines(text: string, n: number): string {
+	const lines = text.split("\n");
+	return lines.slice(0, n).join("\n");
+}

package/index.ts

@@ -0,0 +1,61 @@
+/**
+ * Ralph Loop Extension
+ *
+ * Iterative goal-achievement loop with Generator → Critique → Judge agents.
+ * Each step sends a message to chat as it completes — tail -f style.
+ *
+ * Architecture:
+ *   index.ts              — thin entry point, registers command & renderer
+ *   agents/orchestrator   — coordinates the full flow
+ *   agents/generator      — produces or improves a result
+ *   agents/critique       — evaluates a result against the goal
+ *   agents/judge          — decides if the goal is achieved
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { parseArgs } from "./argParser";
+import { renderRalphLoopMessage } from "./renderer";
+import * as Orchestrator from "./agents/orchestrator";
+
+export default function (pi: ExtensionAPI) {
+
+	pi.registerCommand("ralph-loop-anything", {
+		description: "Run a dynamic Ralph loop (Generator->Critique->Judge) to achieve a goal",
+		getArgumentCompletions: (prefix: string) => {
+			const items = [
+				{ value: '--goal "', label: '--goal "specify your goal"' },
+				{ value: "--loop ", label: "--loop N (default 3)" },
+			];
+			const filtered = items.filter((i) =>
+				i.value.startsWith(prefix) || i.label.startsWith(prefix)
+			);
+			return filtered.length > 0 ? filtered : null;
+		},
+		handler: async (args, ctx) => {
+			let parsed: ReturnType<typeof parseArgs>;
+			try {
+				parsed = parseArgs(args);
+			} catch (err: any) {
+				ctx.ui.notify(`Failed: ${err.message}`, "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected. Use /model to select one.", "error");
+				return;
+			}
+
+			ctx.ui.notify(`Ralph Loop: "${parsed.goal}" (max ${parsed.loop} iterations)`, "info");
+
+			await Orchestrator.execute(pi, ctx, {
+				goal: parsed.goal,
+				maxLoops: parsed.loop,
+			});
+		},
+	});
+
+	pi.registerMessageRenderer("ralph-loop", (message, theme) => {
+		return renderRalphLoopMessage(message, theme);
+	});
+}

package/llm.ts

@@ -0,0 +1,85 @@
+// ============================================================================
+// LLM Client
+// ============================================================================
+
+import { complete, type UserMessage } from "@earendil-works/pi-ai";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { OneshotResult } from "./types";
+
+/**
+ * Make a oneshot LLM call with system prompt + user message.
+ */
+export async function oneshotLLM(
+	ctx: ExtensionCommandContext,
+	systemPrompt: string,
+	userMessage: string,
+	signal?: AbortSignal,
+): Promise<OneshotResult> {
+	if (!ctx.model) {
+		return { text: "", error: "No model selected" };
+	}
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model);
+	if (!auth.ok || !auth.apiKey) {
+		return { text: "", error: auth.ok ? `No API key for ${ctx.model.provider}` : auth.error };
+	}
+
+	const messages: UserMessage[] = [
+		{
+			role: "user",
+			content: [{ type: "text", text: userMessage }],
+			timestamp: Date.now(),
+		},
+	];
+
+	try {
+		const response = await complete(
+			ctx.model,
+			{ systemPrompt, messages },
+			{ apiKey: auth.apiKey, headers: auth.headers, signal },
+		);
+
+		if (response.stopReason === "aborted") {
+			return { text: "", error: "Aborted" };
+		}
+
+		const text = response.content
+			.filter((c): c is { type: "text"; text: string } => c.type === "text")
+			.map((c) => c.text)
+			.join("\n");
+
+		return { text };
+	} catch (err: any) {
+		return { text: "", error: err.message || String(err) };
+	}
+}
+
+// ============================================================================
+// JSON Response Parsing
+// ============================================================================
+
+/**
+ * Parse JSON from LLM response. Handles plain JSON, JSON in code blocks,
+ * or JSON extracted via regex from mixed content.
+ */
+export function parseJsonResponse<T = Record<string, unknown>>(text: string): T | null {
+	try {
+		return JSON.parse(text.trim());
+	} catch {}
+
+	const jsonMatch = text.match(/\{[\s\S]*\}/);
+	if (jsonMatch) {
+		try {
+			return JSON.parse(jsonMatch[0]);
+		} catch {}
+	}
+
+	const fenceMatch = text.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+	if (fenceMatch) {
+		try {
+			return JSON.parse(fenceMatch[1]);
+		} catch {}
+	}
+
+	return null;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@entelligentsia/pi-ralph",
+  "version": "1.0.0",
+  "description": "Iterative goal-achievement loop for pi — Generator→Critique→Judge, streaming output as it happens",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "llm",
+    "agent",
+    "iterative",
+    "refinement"
+  ],
+  "license": "MIT",
+  "author": "Entelligentsia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Entelligentsia/pi-ralph.git"
+  },
+  "homepage": "https://github.com/Entelligentsia/pi-ralph#readme",
+  "bugs": {
+    "url": "https://github.com/Entelligentsia/pi-ralph/issues"
+  },
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "types.ts",
+    "renderer.ts",
+    "prompts.ts",
+    "helpers.ts",
+    "llm.ts",
+    "argParser.ts",
+    "agents/"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/prompts.ts

@@ -0,0 +1,82 @@
+// ============================================================================
+// Static System Prompts
+// ============================================================================
+
+export const FEASIBILITY_PROMPT = `You are a goal feasibility evaluator. Your job is to determine whether a given goal can be meaningfully pursued and achieved using an LLM.
+
+Consider:
+- Is the goal well-defined enough for an LLM to work on?
+- Can an LLM make meaningful progress on this goal (e.g., through text, code, analysis, planning)?
+- Is the goal something that requires physical action that an LLM cannot do (e.g., "cook an omelette")?
+- Could the goal be reinterpreted in a way that an LLM can contribute meaningfully?
+
+For example:
+- "Write a poem" → achievable (text generation)
+- "Sort a list" → achievable (code generation)
+- "Make me an omelette" → NOT achievable (requires physical action)
+- "Design a car" → achievable if interpreted as "create a detailed car design document"
+
+You MUST respond with ONLY a JSON object (no markdown fences, no extra text):
+{"achievable": true, "reason": "brief explanation"}
+or
+{"achievable": false, "reason": "brief explanation"}`;
+
+export const PROMPT_GENERATOR_PROMPT = `You are a prompt engineer. Given a goal, you design the system prompts for three specialized agents that will work together in an iterative loop to achieve that goal. Each prompt must be tailored to the goal's domain so the agents are aligned from the start.
+
+The three agents are:
+1. **Generator** — Produces or improves a result for the goal. On iteration >1, it receives the previous result and criticism, so its prompt should instruct it to address feedback.
+2. **Critique** — Evaluates the Generator's output against the goal. Identifies problems, gaps, and suggests concrete improvements.
+3. **Judge** — Determines if the result adequately achieves the goal, given the criticism. Outputs JSON: {"done": true/false, "reason": "..."}
+
+Each system prompt should:
+- Establish the agent's role and expertise relevant to the goal's domain
+- Include domain-specific evaluation criteria (e.g., for code: correctness, efficiency, edge cases; for writing: style, coherence, completeness)
+- Be concise but specific — generic instructions are worse than goal-tailored ones
+- For the Judge, require JSON output format: {"done": true/false, "reason": "brief explanation"}
+- For the Judge, use "done": true only if the result adequately achieves the goal or has reached diminishing returns. Use "done": false if significant improvements are still needed.
+
+You MUST respond with ONLY a JSON object (no markdown fences, no extra text) with exactly these keys:
+{
+  "domain": "the identified domain (e.g., 'Literary Fiction', 'Systems Programming', 'Business Strategy')",
+  "generator_prompt": "...",
+  "critique_prompt": "...",
+  "judge_prompt": "..."
+}`;
+
+// ============================================================================
+// Fallback Prompts (used if dynamic generation fails)
+// ============================================================================
+
+export const FALLBACK_GENERATOR_PROMPT = `You are a Generator agent. Your job is to produce the best possible result for the given goal.
+
+Instructions:
+- Be thorough, creative, and accurate
+- If this is a follow-up iteration, carefully address all criticisms from the previous round
+- Produce a complete, polished result
+- Focus on quality and completeness`;
+
+export const FALLBACK_CRITIQUE_PROMPT = `You are a Critique agent. Your job is to critically evaluate a result against the original goal.
+
+Instructions:
+- Identify what's missing, incorrect, or incomplete
+- Point out any errors or inaccuracies
+- Suggest specific, actionable improvements
+- Be thorough but constructive
+- Rate how well the result achieves the goal on a scale of 1-10
+- Focus on the most important issues first`;
+
+export const FALLBACK_JUDGE_PROMPT = `You are a Judge agent. Your job is to determine whether a result, given its criticism, adequately achieves the original goal.
+
+Instructions:
+- Consider: Does the result address the goal?
+- Consider: Are the criticisms minor or fundamental?
+- Consider: Is the result good enough that further iterations are unlikely to produce significantly better output?
+- Be strict but fair
+
+You MUST respond with ONLY a JSON object (no markdown fences, no extra text):
+{"done": true, "reason": "brief explanation"}
+or
+{"done": false, "reason": "brief explanation"}
+
+Use "done": true ONLY if the result adequately achieves the goal or has reached the point of diminishing returns.
+Use "done": false if significant improvements are still needed.`;

package/renderer.ts

@@ -0,0 +1,19 @@
+// ============================================================================
+// Message Renderer
+//
+// Each message is self-contained markdown — the renderer just passes it
+// through as a Markdown component. No layout, no boxes, no truncation.
+// ============================================================================
+
+import { Markdown } from "@earendil-works/pi-tui";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import type { Theme } from "@earendil-works/pi-tui";
+import type { Message } from "@earendil-works/pi-coding-agent";
+
+export function renderRalphLoopMessage(
+	message: Message,
+	_theme: Theme,
+): Markdown {
+	const content = typeof message.content === "string" ? message.content : "";
+	return new Markdown(content, 0, 0, getMarkdownTheme());
+}

package/types.ts

@@ -0,0 +1,53 @@
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface ParsedArgs {
+	goal: string;
+	loop: number;
+}
+
+export interface OneshotResult {
+	text: string;
+	error?: string;
+}
+
+export interface AgentPrompts {
+	generator_prompt: string;
+	critique_prompt: string;
+	judge_prompt: string;
+}
+
+/**
+ * A single step within a loop iteration.
+ * Each iteration has 4 steps: Generate → Critique → Judge → (implied: Revise)
+ */
+export type LoopStep =
+	| { type: "generate"; preview: string; full: string }
+	| { type: "critique"; preview: string; full: string }
+	| { type: "judge"; verdict: boolean; reason: string; raw: string }
+	| { type: "revision"; reason: string }; // Why we're revising (based on judge verdict)
+
+export interface LoopIteration {
+	loop: number;
+	steps: LoopStep[];
+	achieved: boolean; // did judge say done: true
+	finalResult: string;
+	finalCriticism: string;
+	finalJudgeReason: string;
+}
+
+export interface RalphLoopResult {
+	goal: string;
+	domain: string; // identified domain for the goal
+	maxLoops: number;
+	loopCount: number;
+	achieved: boolean;
+	feasibilityReason: string;
+	feasibilityRaw: string;
+	agentPrompts: AgentPrompts;
+	result: string;
+	criticism: string;
+	judgeReason: string;
+	iterations: LoopIteration[];
+}