cralph 1.0.0-beta.7 → 1.0.0-beta.8

package/README.md

@@ -4,13 +4,13 @@
   <img src="https://raw.githubusercontent.com/mguleryuz/cralph/main/assets/ralph.png" alt="Ralph cooking" width="500">
 </p>
 
-Claude in a loop. Give it a rule, let it cook.
+Claude in a loop. Give it a TODO, let it cook.
 
 ```
 .ralph/
-├── rule.md ──loop──> ./
-├── refs/             (output)
-└── TODO.md
+├── refs/             (read-only reference material)
+├── TODO.md ──loop──> ./
+└── paths.json        (output)
 ```
 
 ## What is Ralph?
@@ -39,7 +39,7 @@ bun add -g cralph
 # In any directory without .ralph/ - creates starter structure
 cralph
 
-# Edit rule.md with your instructions, then run again
+# Run again - prepare your TODO, then run
 cralph
 ```
 
@@ -50,7 +50,7 @@ cralph
 cralph
 
 # Override with flags
-cralph --refs ./source --rule ./rule.md --output .
+cralph --refs ./source --output .
 
 # Auto-confirm prompts (CI/automation)
 cralph --yes
@@ -59,19 +59,63 @@ cralph --yes
 ## How It Works
 
 1. Checks Claude CLI auth (cached for 6 hours)
-2. Looks for `.ralph/` in current directory only (not subdirectories)
-3. Loads config from `.ralph/paths.json` or creates starter structure
+2. Looks for `.ralph/` in current directory
+3. Shows main menu: **Run** / **Prepare TODO** / **Edit config**
 4. Runs `claude -p --dangerously-skip-permissions` in a loop
 5. Claude completes **ONE task per iteration**, marks it done, then stops
 6. Auto-commits progress after each iteration (fails gracefully if no git)
 7. Stops when Claude outputs `<promise>COMPLETE</promise>`
 
+## Main Menu
+
+When `.ralph/paths.json` exists, you get:
+
+```
+❯ Found .ralph/paths.json. What would you like to do?
+● 🚀 Run with this config
+○ 📝 Prepare TODO
+○ ✏️  Edit configuration
+```
+
+- **Run** — validates config and starts the loop
+- **Prepare TODO** — describe your tasks, Claude generates TODO.md, returns to menu
+- **Edit** — re-select refs/output, save config, returns to menu
+
+## Prepare TODO
+
+Selecting **Prepare TODO** prompts you to describe what Claude should work on:
+
+```
+? Describe your tasks (what should Claude work on?):
+> Build a REST API with user auth, add unit tests, setup error handling
+```
+
+Claude generates a structured TODO.md with ordered, actionable tasks:
+
+```markdown
+# Tasks
+
+- [ ] Set up Express server with basic routing
+- [ ] Add user authentication with JWT
+- [ ] Create user CRUD endpoints
+- [ ] Add error handling middleware
+- [ ] Write unit tests for auth module
+- [ ] Write unit tests for user endpoints
+
+---
+
+# Notes
+
+_Append progress and learnings here after each iteration_
+```
+
+You can prepare TODO multiple times — each run overwrites the previous.
+
 ## Config
 
 ```json
 {
   "refs": ["./.ralph/refs"],
-  "rule": "./.ralph/rule.md",
   "output": "."
 }
 ```
@@ -82,10 +126,9 @@ Save as `.ralph/paths.json`. Refs are optional reference material (read-only).
 
 | File | Description |
 |------|-------------|
-| `.ralph/paths.json` | Configuration |
-| `.ralph/rule.md` | Your instructions for Claude |
+| `.ralph/paths.json` | Configuration (refs, output) |
 | `.ralph/refs/` | Optional reference material (read-only) |
-| `.ralph/TODO.md` | Task tracking (updated by Claude) |
+| `.ralph/TODO.md` | Task tracking (generated or manual, updated by Claude) |
 | `.ralph/ralph.log` | Session log |
 | `~/.cralph/auth-cache.json` | Auth cache (6h TTL) |
 
@@ -107,9 +150,6 @@ Claude maintains this structure (one task per iteration):
 - What was implemented
 - Files changed
 - Learnings: patterns discovered, gotchas encountered
-
-## Task 2 - Done
-- ...
 ```
 
 ## First Run (No .ralph/ in cwd)
@@ -124,39 +164,29 @@ Select **Create starter structure** to generate the default config:
 
 ```
 ℹ Created .ralph/refs/ directory
-ℹ Created .ralph/rule.md with starter template
 ℹ Created .ralph/paths.json
 
-╭─────────────────────────────────────────────────╮
-│  1. Add source files to .ralph/refs/            │
-│  2. Edit .ralph/rule.md with your instructions  │
-│  3. Run cralph again                            │
-╰─────────────────────────────────────────────────╯
+╭──────────────────────────────────────────────╮
+│  1. Add source files to .ralph/refs/         │
+│  2. Run cralph again to prepare your TODO    │
+╰──────────────────────────────────────────────╯
 ```
 
-Select **Configure manually** to skip starter creation and pick your own refs/rule/output.
+## TODO Reset
 
-Use `--yes` to auto-create starter structure (for CI/automation).
+When running, if TODO.md has existing progress:
 
-## Prompts
-
-**Config detected:**
 ```
-❯ Found .ralph/paths.json. What would you like to do?
-● 🚀 Run with this config
-○ ✏️  Edit configuration
+? Found existing TODO with progress. Reset to start fresh? (y/N)
 ```
 
-**TODO has progress:**
-```
-? Found existing TODO with progress. Reset to start fresh? (Y/n)
-```
+Default is **No** — continues with existing progress.
 
 ## Path Selection
 
-- **Space** - Toggle selection
-- **Enter** - Confirm
-- **Ctrl+C** - Exit
+- **Space** — Toggle selection
+- **Enter** — Confirm
+- **Ctrl+C** — Exit
 
 ## Platform Support
 
@@ -168,7 +198,7 @@ cralph works on **macOS**, **Linux**, and **Windows** with platform-specific han
 | Linux    | lost+found, proc, sys |
 | Windows  | System Volume Information, $Recycle.Bin, Windows |
 
-Permission errors (`EPERM`, `EACCES`) are handled gracefully on all platforms, allowing the CLI to run from any directory.
+Permission errors (`EPERM`, `EACCES`) are handled gracefully on all platforms.
 
 ## Testing
 
@@ -176,8 +206,8 @@ Permission errors (`EPERM`, `EACCES`) are handled gracefully on all platforms, a
 bun test
 ```
 
-- **Unit tests** - Config, prompt building, CLI, access error handling, platform detection, shutdown state
-- **E2E tests** - Full loop with Claude (requires auth)
+- **Unit tests** — Config, prompt building, CLI, access error handling, platform detection, shutdown state
+- **E2E tests** — Full loop with Claude (requires auth)
 
 ## Requirements
 

package/index.ts

@@ -1,6 +1,6 @@
 // Re-export for programmatic usage
 export * from "./src/types";
-export { loadPathsFile, validateConfig, resolvePathsConfig, toRelativePath } from "./src/paths";
+export { loadPathsFile, validateConfig, resolvePathsConfig, toRelativePath, prepareTodo } from "./src/paths";
 export { createPrompt, buildPrompt } from "./src/prompt";
 export { run, checkClaudeAuth } from "./src/runner";
 export { cleanupSubprocess, setShuttingDown, isShuttingDown } from "./src/state";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cralph",
-  "version": "1.0.0-beta.7",
+  "version": "1.0.0-beta.8",
   "description": "Claude in a loop. Point at refs, give it a rule, let it cook.",
   "author": "mguleryuz",
   "license": "MIT",

package/src/cli.ts

@@ -8,11 +8,11 @@ import {
   loadPathsFile,
   validateConfig,
   selectRefs,
-  selectRule,
   selectOutput,
   checkForPathsFile,
   resolvePathsConfig,
   toRelativePath,
+  prepareTodo,
 } from "./paths";
 import { run, checkClaudeAuth } from "./runner";
 import type { RalphConfig } from "./types";
@@ -47,7 +47,7 @@ const main = defineCommand({
   meta: {
     name: "cralph",
     version: "1.0.0",
-    description: "Claude in a loop. Point at refs, give it a rule, let it cook.",
+    description: "Claude in a loop. Give it a TODO, let it cook.",
   },
   args: {
     refs: {
@@ -57,13 +57,6 @@ const main = defineCommand({
       alias: "r",
       required: false,
     },
-    rule: {
-      type: "string",
-      description: "Path to rule file (.mdc or .md)",
-      valueHint: "rule.md",
-      alias: "u",
-      required: false,
-    },
     output: {
       type: "string",
       description: "Output directory where results will be written",
@@ -113,18 +106,28 @@ const main = defineCommand({
       
       consola.success("Claude authenticated");
 
-      // Check for existing paths file in cwd
-      const pathsFileResult = args.yes 
-        ? await checkForPathsFile(cwd, true) // Auto-run if --yes
-        : await checkForPathsFile(cwd);
-      
-      if (pathsFileResult?.action === "run") {
-        // Use existing config file
-        consola.info(`Loading config from ${pathsFileResult.path}`);
-        const loaded = await loadPathsFile(pathsFileResult.path);
-        config = resolvePathsConfig(loaded, cwd);
-      } else {
-        // Load existing config for edit mode defaults
+      // Main selection loop - prepare/edit return here, run breaks out
+      while (true) {
+        const pathsFileResult = args.yes
+          ? await checkForPathsFile(cwd, true)
+          : await checkForPathsFile(cwd);
+
+        if (pathsFileResult?.action === "prepare") {
+          const loaded = await loadPathsFile(pathsFileResult.path);
+          const resolved = resolvePathsConfig(loaded, cwd);
+          const outputBase = resolved.output === cwd ? cwd : resolved.output;
+          await prepareTodo(outputBase);
+          continue;
+        }
+
+        if (pathsFileResult?.action === "run") {
+          consola.info(`Loading config from ${pathsFileResult.path}`);
+          const loaded = await loadPathsFile(pathsFileResult.path);
+          config = resolvePathsConfig(loaded, cwd);
+          break;
+        }
+
+        // Edit mode or no config found
         let existingConfig: RalphConfig | null = null;
         if (pathsFileResult?.action === "edit") {
           consola.info("Edit configuration");
@@ -139,19 +142,15 @@ const main = defineCommand({
         }
 
         // Interactive selection
-        const refs = args.refs 
+        const refs = args.refs
           ? args.refs.split(",").map((r) => resolve(cwd, r.trim()))
           : await selectRefs(cwd, existingConfig?.refs, args.yes);
-        
-        const rule = args.rule 
-          ? resolve(cwd, args.rule)
-          : await selectRule(cwd, existingConfig?.rule);
-        
-        const output = args.output 
+
+        const output = args.output
           ? resolve(cwd, args.output)
           : await selectOutput(cwd, existingConfig?.output);
 
-        config = { refs, rule, output };
+        config = { refs, output };
 
         // Offer to save config
         const saveConfig = await consola.prompt("Save configuration to .ralph/paths.json?", {
@@ -159,16 +158,15 @@ const main = defineCommand({
           cancel: "symbol",
           initial: true,
         });
-        
+
         throwIfCancelled(saveConfig);
 
         if (saveConfig === true) {
           const ralphDir = join(cwd, ".ralph");
           await mkdir(ralphDir, { recursive: true });
-          
+
           const pathsConfig = {
             refs: config.refs.map((r) => toRelativePath(r, cwd)),
-            rule: toRelativePath(config.rule, cwd),
             output: toRelativePath(config.output, cwd),
           };
           await Bun.write(
@@ -177,8 +175,12 @@ const main = defineCommand({
           );
           consola.success("Saved .ralph/paths.json");
         }
+
+        // After edit, loop back to main selection
+        continue;
       }
 
+
       // Validate configuration
       consola.info("Validating configuration...");
       await validateConfig(config);
@@ -186,7 +188,6 @@ const main = defineCommand({
       // Show config summary
       consola.info("Configuration:");
       consola.info(`  Refs: ${config.refs.join(", ")}`);
-      consola.info(`  Rule: ${config.rule}`);
       consola.info(`  Output: ${config.output}`);
       console.log();
 

package/src/paths.ts

@@ -6,10 +6,6 @@ import type { PathsFileConfig, RalphConfig } from "./types";
 import { isAccessError, shouldExcludeDir } from "./platform";
 import { throwIfCancelled } from "./state";
 
-// Starter rule template for new projects
-const STARTER_RULE = `I want a file named hello.txt
-`;
-
 // Dim text helper
 const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
 const CONTROLS = dim("↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit");
@@ -20,7 +16,6 @@ const CONTROLS = dim("↑↓ Navigate • Space Toggle • Enter • Ctrl+C Exit
 export function resolvePathsConfig(loaded: PathsFileConfig, cwd: string): RalphConfig {
   return {
     refs: loaded.refs.map((r) => resolve(cwd, r)),
-    rule: resolve(cwd, loaded.rule),
     output: resolve(cwd, loaded.output),
   };
 }
@@ -38,6 +33,7 @@ export function toRelativePath(absolutePath: string, cwd: string): string {
  */
 function shouldSkipDirectory(entry: Dirent): boolean {
   if (!entry.isDirectory()) return true;
+  if (entry.name === ".ralph") return false; // Always show .ralph
   if (entry.name.startsWith(".")) return true;
   if (shouldExcludeDir(entry.name)) return true;
   return false;
@@ -50,7 +46,7 @@ async function listDirectories(basePath: string): Promise<string[]> {
   try {
     const entries = await readdir(basePath, { withFileTypes: true });
     return entries
-      .filter((e) => e.isDirectory() && !e.name.startsWith("."))
+      .filter((e) => e.isDirectory() && (e.name === ".ralph" || !e.name.startsWith(".")))
       .map((e) => e.name);
   } catch (error) {
     // Silently skip directories we can't access
@@ -154,27 +150,21 @@ export async function createStarterStructure(cwd: string): Promise<void> {
   // Create .ralph/
   const ralphDir = join(cwd, ".ralph");
   await mkdir(ralphDir, { recursive: true });
-  
+
   // Create .ralph/refs/
   const refsDir = join(ralphDir, "refs");
   await mkdir(refsDir, { recursive: true });
   consola.info("Created .ralph/refs/ directory");
-  
-  // Create .ralph/rule.md
-  const rulePath = join(ralphDir, "rule.md");
-  await Bun.write(rulePath, STARTER_RULE);
-  consola.info("Created .ralph/rule.md with starter template");
-  
+
   // Create .ralph/paths.json with default config
   const pathsConfig = {
     refs: ["./.ralph/refs"],
-    rule: "./.ralph/rule.md",
     output: ".",
   };
   await Bun.write(join(ralphDir, "paths.json"), JSON.stringify(pathsConfig, null, 2));
   consola.info("Created .ralph/paths.json");
-  
-  consola.box("1. Add source files to .ralph/refs/\n2. Edit .ralph/rule.md with your instructions\n3. Run cralph again");
+
+  consola.box("1. Add source files to .ralph/refs/\n2. Run cralph again to prepare your TODO");
 }
 
 /**
@@ -263,39 +253,80 @@ export async function selectRefs(cwd: string, defaults?: string[], autoConfirm?:
 }
 
 /**
- * Prompt user to select a rule file
+ * Prompt user to prepare TODO.md by describing their tasks
+ * Uses Claude to generate a properly formatted TODO.md
  */
-export async function selectRule(cwd: string, defaultRule?: string): Promise<string> {
-  let files = await listFilesRecursive(cwd, [".mdc", ".md"]);
-  if (files.length === 0) {
-    // This shouldn't happen if selectRefs ran first, but handle it just in case
-    const rulePath = join(cwd, "rule.md");
-    await Bun.write(rulePath, STARTER_RULE);
-    consola.info("Created rule.md with starter template");
-    consola.box("Edit rule.md with your instructions then run cralph again");
-    process.exit(0);
+export async function prepareTodo(cwd: string): Promise<void> {
+  const ralphDir = join(cwd, ".ralph");
+  const todoPath = join(ralphDir, "TODO.md");
+
+  const description = await consola.prompt(
+    "Describe your tasks (what should Claude work on?):",
+    {
+      type: "text",
+      cancel: "symbol",
+      placeholder: "e.g. Build a REST API with user auth, add tests, setup CI...",
+    }
+  );
+
+  throwIfCancelled(description);
+
+  if (!description || (description as string).trim() === "") {
+    consola.warn("No description provided, skipping TODO preparation");
+    return;
   }
 
-  // Show relative paths for readability
-  const options = files.map((f) => ({
-    label: `📄 ${f.replace(cwd + "/", "")}`,
-    value: f,
-    hint: f === defaultRule ? "current" : (f.endsWith(".mdc") ? "cursor rule" : "markdown"),
-  }));
+  consola.start("Generating TODO.md from your description...");
 
-  // Find initial value for default selection
-  const initialValue = defaultRule && files.includes(defaultRule) ? defaultRule : files[0];
+  const todoPrompt = `You are generating a TODO.md file for an autonomous coding agent. Based on the user's description, create a well-structured TODO.md with clear, actionable tasks.
 
-  console.log(CONTROLS);
-  const selected = await consola.prompt("Select rule file:", {
-    type: "select",
-    cancel: "symbol",
-    options,
-    initial: initialValue,
-  });
+Rules:
+- Each task should be a single, focused unit of work
+- Tasks should be ordered logically (dependencies first)
+- Use the checkbox format: "- [ ] Task description"
+- Keep task descriptions concise but specific
+- Include a Notes section placeholder at the bottom
 
-  throwIfCancelled(selected);
-  return selected as string;
+User's description:
+${(description as string).trim()}
+
+Output ONLY the TODO.md content, nothing else. Use this exact format:
+
+# Tasks
+
+- [ ] First task
+- [ ] Second task
+...
+
+---
+
+# Notes
+
+_Append progress and learnings here after each iteration_`;
+
+  try {
+    const proc = Bun.spawn(["claude", "-p"], {
+      stdin: new Blob([todoPrompt]),
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const stdout = await new Response(proc.stdout).text();
+    const exitCode = await proc.exited;
+
+    if (exitCode !== 0) {
+      consola.error("Failed to generate TODO.md");
+      return;
+    }
+
+    // Write the generated TODO
+    await mkdir(ralphDir, { recursive: true });
+    await Bun.write(todoPath, stdout.trim() + "\n");
+    consola.success("Generated .ralph/TODO.md");
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    consola.error(`Failed to generate TODO: ${msg}`);
+  }
 }
 
 /**
@@ -340,19 +371,18 @@ export async function selectOutput(cwd: string, defaultOutput?: string): Promise
 
 /**
  * Check if a paths file exists and offer to use it
- * Returns: { action: "run", path: string } | { action: "edit" } | null
  * @param autoRun - If true, skip prompt and auto-select "run" when config exists
  */
-export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise<{ action: "run"; path: string } | { action: "edit" } | null> {
+export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise<{ action: "run" | "edit" | "prepare"; path: string } | null> {
   const filePath = join(cwd, ".ralph", "paths.json");
   const file = Bun.file(filePath);
-  
+
   if (await file.exists()) {
     // Auto-run if flag is set
     if (autoRun) {
       return { action: "run", path: filePath };
     }
-    
+
     console.log(CONTROLS);
     const action = await consola.prompt(
       `Found .ralph/paths.json. What would you like to do?`,
@@ -361,17 +391,15 @@ export async function checkForPathsFile(cwd: string, autoRun?: boolean): Promise
         cancel: "symbol",
         options: [
           { label: "🚀 Run with this config", value: "run" },
+          { label: "📝 Prepare TODO", value: "prepare" },
           { label: "✏️  Edit configuration", value: "edit" },
         ],
       }
     );
-    
+
     throwIfCancelled(action);
-    
-    if (action === "run") {
-      return { action: "run", path: filePath };
-    }
-    return { action: "edit" };
+
+    return { action: action as "run" | "edit" | "prepare", path: filePath };
   }
 
   return null;
@@ -390,11 +418,5 @@ export async function validateConfig(config: RalphConfig): Promise<void> {
     }
   }
 
-  // Check rule file
-  const ruleFile = Bun.file(config.rule);
-  if (!(await ruleFile.exists())) {
-    throw new Error(`Rule file does not exist: ${config.rule}`);
-  }
-
   // Output directory will be created if needed
 }

package/src/prompt.ts

@@ -6,8 +6,6 @@ import type { RalphConfig } from "./types";
  */
 const BASE_PROMPT = `You are an autonomous coding agent running in a loop.
 
-FIRST: Read and internalize the rules provided below.
-
 ## Your Task This Iteration
 
 1. Read the TODO file
@@ -55,10 +53,10 @@ After completing ONE task, check the TODO file:
 **IMPORTANT:** Do NOT continue to the next task. Complete ONE task, then STOP.`;
 
 /**
- * Build the complete prompt with config and rules injected
+ * Build the complete prompt with config injected
  */
-export function buildPrompt(config: RalphConfig, rulesContent: string, todoFile: string): string {
-  const refsList = config.refs.length > 0 
+export function buildPrompt(config: RalphConfig, todoFile: string): string {
+  const refsList = config.refs.length > 0
     ? config.refs.map((r) => `- ${r}`).join("\n")
     : "_None_";
 
@@ -76,21 +74,12 @@ ${refsList}
 
 **Output directory (write your work here):**
 ${config.output}
-
----
-
-## Rules (Your Instructions)
-
-${rulesContent}
 `;
 }
 
 /**
- * Read rule file and build complete prompt
+ * Build the complete prompt from config
  */
 export async function createPrompt(config: RalphConfig, todoFile: string): Promise<string> {
-  const ruleFile = Bun.file(config.rule);
-  const ruleContent = await ruleFile.text();
-
-  return buildPrompt(config, ruleContent, todoFile);
+  return buildPrompt(config, todoFile);
 }

package/src/runner.ts

@@ -152,7 +152,7 @@ Ralph Session: ${state.startTime.toISOString()}
       {
         type: "confirm",
         cancel: "symbol",
-        initial: true,
+        initial: false,
       }
     );
     

package/src/types.ts

@@ -3,7 +3,6 @@
  */
 export interface PathsFileConfig {
   refs: string[];
-  rule: string;
   output: string;
 }
 
@@ -13,8 +12,6 @@ export interface PathsFileConfig {
 export interface RalphConfig {
   /** Paths to reference material directories/files */
   refs: string[];
-  /** Path to the rule file (.mdc or .md) */
-  rule: string;
   /** Output directory for generated docs */
   output: string;
 }