feat: add Ralph workspace scaffolding to the TUI

apps/tui/package.json

@@ -20,11 +20,12 @@
 		"typescript": "^5"
 	},
 	"dependencies": {
-		"@techatnyu/ralphd": "workspace:*",
 		"@crustjs/core": "^0.0.13",
+		"@crustjs/create": "^0.0.4",
 		"@crustjs/plugins": "^0.0.16",
 		"@opentui/core": "^0.1.77",
 		"@opentui/react": "^0.1.77",
+		"@techatnyu/ralphd": "workspace:*",
 		"react": "^19.2.4"
 	}
 }

apps/tui/src/scaffold.ts

@@ -0,0 +1,56 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { scaffold } from "@crustjs/create";
+import { resolveDaemonPaths } from "@techatnyu/ralphd";
+
+export interface SessionScaffoldOptions {
+	instanceId: string;
+	sessionId: string;
+	ralphHome?: string;
+}
+
+function assertValidSegment(value: string, label: string): void {
+	if (!value.trim()) {
+		throw new Error(`${label} is required`);
+	}
+
+	if (value.includes("/") || value.includes("\\")) {
+		throw new Error(`${label} must not contain path separators`);
+	}
+}
+
+export function resolveSessionScaffoldPath(
+	options: SessionScaffoldOptions,
+): string {
+	assertValidSegment(options.instanceId, "instanceId");
+	assertValidSegment(options.sessionId, "sessionId");
+
+	const ralphHome =
+		options.ralphHome ?? resolveDaemonPaths(process.env).ralphHome;
+
+	return join(
+		ralphHome,
+		"sessions",
+		options.instanceId,
+		options.sessionId,
+	);
+}
+
+export async function bootstrapSessionScaffold(
+	options: SessionScaffoldOptions,
+): Promise<string> {
+	const sessionPath = resolveSessionScaffoldPath(options);
+
+	await mkdir(sessionPath, { recursive: true });
+
+	await scaffold({
+		template: new URL("../templates/ralph-workspace", import.meta.url),
+		dest: sessionPath,
+		context: {
+			instanceId: options.instanceId,
+			sessionId: options.sessionId,
+		},
+	});
+
+	return sessionPath;
+}

apps/tui/templates/ralph-workspace/PROMPT.md

@@ -0,0 +1,109 @@
+# Ralph Agent Instructions
+
+You are an AI coding agent working through a project task by task. Each session, you complete EXACTLY ONE task and hand off to the next iteration.
+
+## Step 1: Understand Context
+
+Read these files to understand the current state:
+
+1. **`SPEC.md`** - Project specification (what you're building)
+2. **`prd.json`** - Task list with all tasks and their status
+3. **`progress.md`** - Log of completed work and notes from previous iterations
+
+> **Note**: These files may be located in a `.ralph/` subdirectory (e.g., `.ralph/SPEC.md`, `.ralph/prd.json`, `.ralph/progress.md`). Check both locations.
+
+## Step 2: Select a Task
+
+From `prd.json`, select **ONE** task to work on:
+
+- Choose a task where `passed: false`
+- Analyze task descriptions and the current project state to determine the best task to work on next
+- Consider logical dependencies (e.g., "add authentication" should come before "add protected routes")
+- If unclear, prefer tasks listed earlier in the file
+
+## Step 3: Complete the Task
+
+Work through the task:
+
+1. Follow the `subtasks` array as your implementation guide
+2. Write clean, well-structured code
+3. **Verify your work** before marking complete:
+   - Run tests if they exist
+   - Run type checks if applicable (`tsc --noEmit`, `mypy`, etc.)
+   - Run linting if configured
+   - Manually verify the feature works as expected
+
+## Step 4: Update Progress
+
+After completing the task, update `progress.md`:
+
+### Format
+
+Each entry should be separated by "---" and include:
+
+- Task: The task description from prd.json
+- Completed: What was accomplished
+- Files Changed: List of modified files
+- Decisions: Key architectural or implementation decisions
+- Notes for Next Agent: Context for future iterations
+
+### Rules
+
+- **APPEND ONLY**: Never modify or delete previous entries
+- Each new entry starts with "---" separator
+- Be specific about what was done and why
+- Leave helpful context for future iterations
+
+### Example Entry
+
+```markdown
+---
+
+## Task: [Task description from prd.json]
+
+### Completed
+
+- [What you accomplished]
+
+### Files Changed
+
+- [List of files]
+
+### Decisions
+
+- [Any architectural or implementation decisions]
+
+### Notes for Future Agent
+
+- [Helpful context for future iterations]
+```
+
+## Step 5: Update prd.json
+
+1. Set `passed: true` for the completed task
+2. Update `notes` field of **any other tasks** if you discovered relevant context that is helpful for completing the given task
+
+## Step 6: Commit Changes
+
+- Create a git commit with a clear, descriptive message.
+- Include what was implemented, not just "completed task"
+
+## Step 7: Signal Completion
+
+When finished, output this exact string on its own line:
+
+```
+RALPH_TASK_COMPLETE
+```
+
+This signals the orchestration script to start the next iteration.
+
+---
+
+## Important Rules
+
+1. **One task per session** - Do not work on multiple tasks
+2. **Verify before marking complete** - Ensure the implementation actually works
+3. **Append-only progress** - Never edit previous progress.md entries
+4. **Leave context** - Future iterations depend on your notes
+5. **Commit your work** - All changes must be committed before signaling completion

apps/tui/templates/ralph-workspace/SPEC.md

@@ -0,0 +1 @@
+# Instance {{instanceId}} Session {{sessionId}}

apps/tui/templates/ralph-workspace/config

@@ -0,0 +1,5 @@
+RALPH_AGENT_CMD="opencode run"
+RALPH_PROMPT_FILE="PROMPT.md"
+RALPH_SPEC_FILE="SPEC.md"
+RALPH_PRD_FILE="prd.json"
+RALPH_PROGRESS_FILE="progress.md"

apps/tui/templates/ralph-workspace/prd.json

@@ -0,0 +1,3 @@
+{
+	"tasks": []
+}

apps/tui/templates/ralph-workspace/progress.md

@@ -0,0 +1 @@
+# Progress Log

packages/daemon/src/index.ts

@@ -1,9 +1,10 @@
 export { DaemonClient, daemon } from "./client";
+export { RALPH_HOME, resolveDaemonPaths } from "./env";
 export {
 	ensureDaemonRunning,
 	runForegroundDaemon,
 	startDetached,
 	stopDaemon,
 	waitUntilReady,
 } from "./launcher";
-export type * from "./protocol";
+export type * from "./protocol";