ralph-cli-sandboxed 0.2.6 → 0.2.7

package/dist/commands/docker.js

@@ -113,6 +113,7 @@ RUN ${gitCommands.join(' \\\n    && ')}
     // Build asciinema installation section if enabled
     let asciinemaInstall = '';
     let asciinemaDir = '';
+    let streamScriptCopy = '';
     if (dockerConfig?.asciinema?.enabled) {
         const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
         asciinemaInstall = `
@@ -123,6 +124,14 @@ RUN apt-get update && apt-get install -y asciinema && rm -rf /var/lib/apt/lists/
 # Create asciinema recordings directory
 RUN mkdir -p /workspace/${outputDir} && chown node:node /workspace/${outputDir}
 `;
+        // Add stream script if streamJson is enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamScriptCopy = `
+# Copy ralph stream wrapper script for clean JSON output
+COPY ralph-stream.sh /usr/local/bin/ralph-stream.sh
+RUN chmod +x /usr/local/bin/ralph-stream.sh
+`;
+        }
     }
     return `# Ralph CLI Sandbox Environment
 # Based on Claude Code devcontainer
@@ -218,7 +227,7 @@ ENV EDITOR=nano
 # Add bash aliases and prompt (fallback if using bash)
 RUN echo 'alias ll="ls -la"' >> /etc/bash.bashrc && \\
     echo 'PS1="\\[\\033[43;30m\\][ralph]\\w\\[\\033[0m\\]\\$ "' >> /etc/bash.bashrc
-${rootBuildCommands}${asciinemaInstall}
+${rootBuildCommands}${asciinemaInstall}${streamScriptCopy}
 # Switch to non-root user
 USER node
 ${gitConfigSection}${nodeBuildCommands}
@@ -364,11 +373,21 @@ function generateDockerCompose(imageName, dockerConfig) {
     }
     // Build command section if configured
     let commandSection = '';
+    let streamJsonNote = '';
     if (dockerConfig?.asciinema?.enabled && dockerConfig?.asciinema?.autoRecord) {
         // Wrap with asciinema recording
         const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
         const innerCommand = dockerConfig.startCommand || 'zsh';
         commandSection = `    command: bash -c "mkdir -p /workspace/${outputDir} && asciinema rec -c '${innerCommand}' /workspace/${outputDir}/session-$$(date +%Y%m%d-%H%M%S).cast"\n`;
+        // Add note about stream-json if enabled
+        if (dockerConfig.asciinema.streamJson?.enabled) {
+            streamJsonNote = `
+    # Stream JSON mode enabled - use ralph-stream.sh for clean Claude output:
+    #   ralph-stream.sh -p "your prompt here"
+    # This formats stream-json output for readable terminal display.
+    # Raw JSON is saved to ${outputDir}/session-*.jsonl for later analysis.
+`;
+        }
     }
     else if (dockerConfig?.startCommand) {
         commandSection = `    command: ${dockerConfig.startCommand}\n`;
@@ -394,7 +413,7 @@ ${environmentSection}    working_dir: /workspace
     tty: true
     cap_add:
       - NET_ADMIN  # Required for firewall
-${commandSection}
+${streamJsonNote}${commandSection}
 volumes:
   ${imageName}-history:
 `;
@@ -405,6 +424,82 @@ dist
 .git
 *.log
 `;
+// Generate stream wrapper script for clean asciinema recordings
+function generateStreamScript(outputDir, saveRawJson) {
+    const saveJsonSection = saveRawJson ? `
+# Save raw JSON for later analysis
+JSON_LOG="$OUTPUT_DIR/session-$TIMESTAMP.jsonl"
+TEE_CMD="tee \\"$JSON_LOG\\""` : `
+TEE_CMD="cat"`;
+    return `#!/bin/bash
+# Ralph stream wrapper - formats Claude stream-json output for clean terminal display
+# Generated by ralph-cli
+
+set -e
+
+OUTPUT_DIR="\${RALPH_RECORDING_DIR:-/workspace/${outputDir}}"
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
+
+# Ensure output directory exists
+mkdir -p "$OUTPUT_DIR"
+${saveJsonSection}
+
+# jq filter to extract and format content from stream-json
+# Handles text, tool calls, tool results, file operations, and commands
+JQ_FILTER='
+  if .type == "content_block_delta" then
+    (if .delta.type == "text_delta" then .delta.text // empty
+     elif .delta.text then .delta.text
+     else empty end)
+  elif .type == "content_block_start" then
+    (if .content_block.type == "tool_use" then "\\n── Tool: " + (.content_block.name // "unknown") + " ──\\n"
+     elif .content_block.type == "text" then .content_block.text // empty
+     else empty end)
+  elif .type == "tool_result" then
+    "\\n── Tool Result ──\\n" + ((.content // .output // "") | tostring) + "\\n"
+  elif .type == "assistant" then
+    ([.message.content[]? | select(.type == "text") | .text] | join(""))
+  elif .type == "message_start" then
+    "\\n"
+  elif .type == "message_delta" then
+    (if .delta.stop_reason then "\\n[" + .delta.stop_reason + "]\\n" else empty end)
+  elif .type == "file_edit" or .type == "file_write" then
+    "\\n── Writing: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "file_read" then
+    "── Reading: " + (.path // .file // "unknown") + " ──\\n"
+  elif .type == "bash" or .type == "command" then
+    "\\n── Running: " + (.command // .content // "") + " ──\\n"
+  elif .type == "bash_output" or .type == "command_output" then
+    (.output // .content // "") + "\\n"
+  elif .type == "result" then
+    (if .result then "\\n── Result ──\\n" + (.result | tostring) + "\\n" else empty end)
+  elif .type == "error" then
+    "\\n[Error] " + (.error.message // (.error | tostring)) + "\\n"
+  elif .type == "system" then
+    (if .message then "[System] " + .message + "\\n" else empty end)
+  elif .text then
+    .text
+  elif (.content | type) == "string" then
+    .content
+  else
+    empty
+  end
+'
+
+# Pass all arguments to claude with stream-json output
+# Filter JSON lines, optionally save raw JSON, and display formatted text
+claude \\
+  --output-format stream-json \\
+  --verbose \\
+  --print \\
+  "\$@" 2>&1 \\
+| grep --line-buffered '^{' \\
+| eval $TEE_CMD \\
+| jq --unbuffered -rj "$JQ_FILTER"
+
+echo ""  # Ensure final newline
+`;
+}
 // Generate .mcp.json content for Claude Code MCP servers
 function generateMcpJson(mcpServers) {
     return JSON.stringify({ mcpServers }, null, 2);
@@ -432,6 +527,12 @@ async function generateFiles(ralphDir, language, imageName, force = false, javaV
         { name: "docker-compose.yml", content: generateDockerCompose(imageName, dockerConfig) },
         { name: ".dockerignore", content: DOCKERIGNORE },
     ];
+    // Add stream script if streamJson is enabled
+    if (dockerConfig?.asciinema?.enabled && dockerConfig.asciinema.streamJson?.enabled) {
+        const outputDir = dockerConfig.asciinema.outputDir || '.recordings';
+        const saveRawJson = dockerConfig.asciinema.streamJson.saveRawJson !== false; // default true
+        files.push({ name: "ralph-stream.sh", content: generateStreamScript(outputDir, saveRawJson) });
+    }
     for (const file of files) {
         const filePath = join(dockerDir, file.name);
         if (existsSync(filePath) && !force) {

package/dist/commands/init.js

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
 import { join, basename, dirname } from "path";
 import { fileURLToPath } from "url";
-import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders } from "../templates/prompts.js";
+import { getLanguages, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS, getCliProviders, getSkillsForLanguage } from "../templates/prompts.js";
 import { promptSelectWithArrows, promptConfirm, promptInput, promptMultiSelectWithArrows } from "../utils/prompt.js";
 import { dockerInit } from "./docker.js";
 // Get package root directory (works for both dev and installed package)
@@ -39,6 +39,7 @@ export async function init(args) {
     let cliConfig;
     let selectedKey;
     let selectedTechnologies = [];
+    let selectedSkills = [];
     let checkCommand;
     let testCommand;
     if (useDefaults) {
@@ -115,6 +116,29 @@ export async function init(args) {
                 console.log("\nNo technologies selected.");
             }
         }
+        // Step 4: Select skills if available for this language
+        const availableSkills = getSkillsForLanguage(selectedKey);
+        if (availableSkills.length > 0) {
+            const skillOptions = availableSkills.map(s => `${s.name} - ${s.description}`);
+            const selectedSkillNames = await promptMultiSelectWithArrows("Select AI coding rules/skills to enable (optional):", skillOptions);
+            // Convert selected display names to SkillConfig objects
+            selectedSkills = selectedSkillNames.map(sel => {
+                const idx = skillOptions.indexOf(sel);
+                const skill = availableSkills[idx];
+                return {
+                    name: skill.name,
+                    description: skill.description,
+                    instructions: skill.instructions,
+                    userInvocable: skill.userInvocable,
+                };
+            });
+            if (selectedSkills.length > 0) {
+                console.log(`\nSelected skills: ${selectedSkills.map(s => s.name).join(", ")}`);
+            }
+            else {
+                console.log("\nNo skills selected.");
+            }
+        }
         // Allow custom commands for "none" language
         checkCommand = config.checkCommand;
         testCommand = config.testCommand;
@@ -164,6 +188,10 @@ export async function init(args) {
                 enabled: false,
                 autoRecord: false,
                 outputDir: ".recordings",
+                streamJson: {
+                    enabled: false,
+                    saveRawJson: true,
+                },
             },
             firewall: {
                 allowedDomains: [],
@@ -172,7 +200,7 @@ export async function init(args) {
         // Claude-specific configuration (MCP servers and skills)
         claude: {
             mcpServers: {},
-            skills: [],
+            skills: selectedSkills,
         },
     };
     const configPath = join(ralphDir, CONFIG_FILE);

package/dist/commands/once.js

@@ -1,6 +1,139 @@
 import { spawn } from "child_process";
+import { existsSync, appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
+/**
+ * Parses a stream-json line and extracts displayable text.
+ * Formats output similar to Claude Code's normal terminal display.
+ */
+function parseStreamJsonLine(line, debug = false) {
+    try {
+        const json = JSON.parse(line);
+        if (debug && json.type) {
+            process.stderr.write(`[stream-json] type: ${json.type}\n`);
+        }
+        // Handle Claude Code CLI stream-json events
+        const type = json.type;
+        switch (type) {
+            // === Text Content ===
+            case "content_block_delta":
+                // Incremental text updates - the main streaming content
+                if (json.delta?.type === "text_delta") {
+                    return json.delta.text || "";
+                }
+                // Tool input being streamed
+                if (json.delta?.type === "input_json_delta") {
+                    return ""; // Don't show partial JSON, wait for complete tool call
+                }
+                return json.delta?.text || "";
+            case "text":
+                return json.text || "";
+            // === Tool Use ===
+            case "content_block_start":
+                if (json.content_block?.type === "tool_use") {
+                    const toolName = json.content_block?.name || "unknown";
+                    return `\n── Tool: ${toolName} ──\n`;
+                }
+                if (json.content_block?.type === "text") {
+                    return json.content_block?.text || "";
+                }
+                return "";
+            case "content_block_stop":
+                // End of a content block - add newline after tool use
+                return "";
+            // === Tool Results ===
+            case "tool_result":
+                const toolOutput = json.content || json.output || "";
+                const truncated = typeof toolOutput === "string" && toolOutput.length > 500
+                    ? toolOutput.substring(0, 500) + "... (truncated)"
+                    : toolOutput;
+                return `\n── Tool Result ──\n${typeof truncated === "string" ? truncated : JSON.stringify(truncated, null, 2)}\n`;
+            // === Assistant Messages ===
+            case "assistant":
+                const contents = json.message?.content || json.content || [];
+                let output = "";
+                for (const block of contents) {
+                    if (block.type === "text") {
+                        output += block.text || "";
+                    }
+                    else if (block.type === "tool_use") {
+                        output += `\n── Tool: ${block.name} ──\n`;
+                        if (block.input) {
+                            output += JSON.stringify(block.input, null, 2) + "\n";
+                        }
+                    }
+                }
+                return output;
+            case "message_start":
+                // Beginning of a new message
+                return "\n";
+            case "message_delta":
+                // Message completion info (stop_reason, usage)
+                if (json.delta?.stop_reason) {
+                    return `\n[${json.delta.stop_reason}]\n`;
+                }
+                return "";
+            case "message_stop":
+                return "\n";
+            // === System/User Events ===
+            case "system":
+                if (json.message) {
+                    return `[System] ${json.message}\n`;
+                }
+                return "";
+            case "user":
+                // User message echo - usually not needed to display
+                return "";
+            // === Results and Errors ===
+            case "result":
+                if (json.result !== undefined) {
+                    return `\n── Result ──\n${JSON.stringify(json.result, null, 2)}\n`;
+                }
+                return "";
+            case "error":
+                const errMsg = json.error?.message || JSON.stringify(json.error);
+                return `\n[Error] ${errMsg}\n`;
+            // === File Operations (Claude Code specific) ===
+            case "file_edit":
+            case "file_write":
+                const filePath = json.path || json.file || "unknown";
+                return `\n── Writing: ${filePath} ──\n`;
+            case "file_read":
+                const readPath = json.path || json.file || "unknown";
+                return `── Reading: ${readPath} ──\n`;
+            case "bash":
+            case "command":
+                const cmd = json.command || json.content || "";
+                return `\n── Running: ${cmd} ──\n`;
+            case "bash_output":
+            case "command_output":
+                const cmdOutput = json.output || json.content || "";
+                return cmdOutput + "\n";
+            default:
+                // Fallback: check for common text fields
+                if (json.text)
+                    return json.text;
+                if (json.content && typeof json.content === "string")
+                    return json.content;
+                if (json.message && typeof json.message === "string")
+                    return json.message;
+                if (json.output && typeof json.output === "string")
+                    return json.output;
+                if (debug) {
+                    process.stderr.write(`[stream-json] unhandled type: ${type}, keys: ${Object.keys(json).join(", ")}\n`);
+                }
+                return "";
+        }
+    }
+    catch (e) {
+        // Not valid JSON
+        if (debug) {
+            process.stderr.write(`[stream-json] parse error: ${e}\n`);
+        }
+        return "";
+    }
+}
 export async function once(args) {
     // Parse flags
     let debug = false;
@@ -32,7 +165,19 @@ export async function once(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
-    console.log("Starting single ralph iteration...\n");
+    // Check if stream-json output is enabled
+    const streamJsonConfig = config.docker?.asciinema?.streamJson;
+    const streamJsonEnabled = streamJsonConfig?.enabled ?? false;
+    const saveRawJson = streamJsonConfig?.saveRawJson !== false; // default true
+    const outputDir = config.docker?.asciinema?.outputDir || ".recordings";
+    console.log("Starting single ralph iteration...");
+    if (streamJsonEnabled) {
+        console.log("Stream JSON output enabled - displaying formatted Claude output");
+        if (saveRawJson) {
+            console.log(`Raw JSON logs will be saved to: ${outputDir}/`);
+        }
+    }
+    console.log();
     // Build CLI arguments: config args + yolo args + model args + prompt args
     // Use yoloArgs from config if available, otherwise default to Claude's --dangerously-skip-permissions
     const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
@@ -42,6 +187,20 @@ export async function once(args) {
         ...(cliConfig.args ?? []),
         ...yoloArgs,
     ];
+    // Add stream-json output format if enabled
+    let jsonLogPath;
+    if (streamJsonEnabled) {
+        cliArgs.push("--output-format", "stream-json", "--verbose", "--print");
+        // Setup JSON log file if saving raw JSON
+        if (saveRawJson) {
+            const fullOutputDir = join(process.cwd(), outputDir);
+            if (!existsSync(fullOutputDir)) {
+                mkdirSync(fullOutputDir, { recursive: true });
+            }
+            const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+            jsonLogPath = join(fullOutputDir, `ralph-once-${timestamp}.jsonl`);
+        }
+    }
     // Add model args if model is specified
     if (model && cliConfig.modelArgs) {
         cliArgs.push(...cliConfig.modelArgs, model);
@@ -49,19 +208,98 @@ export async function once(args) {
     cliArgs.push(...promptArgs, promptValue);
     if (debug) {
         console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+        if (jsonLogPath) {
+            console.log(`[debug] Saving raw JSON to: ${jsonLogPath}\n`);
+        }
     }
     return new Promise((resolve, reject) => {
-        const proc = spawn(cliConfig.command, cliArgs, {
-            stdio: "inherit",
-        });
-        proc.on("close", (code) => {
-            if (code !== 0) {
-                console.error(`\n${cliConfig.command} exited with code ${code}`);
-            }
-            resolve();
-        });
-        proc.on("error", (err) => {
-            reject(new Error(`Failed to start ${cliConfig.command}: ${err.message}`));
-        });
+        if (streamJsonEnabled) {
+            // Stream JSON mode: capture stdout, parse JSON, display clean text
+            let lineBuffer = "";
+            const proc = spawn(cliConfig.command, cliArgs, {
+                stdio: ["inherit", "pipe", "inherit"],
+            });
+            proc.stdout.on("data", (data) => {
+                const chunk = data.toString();
+                lineBuffer += chunk;
+                const lines = lineBuffer.split("\n");
+                // Keep the last incomplete line in the buffer
+                lineBuffer = lines.pop() || "";
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    if (!trimmedLine)
+                        continue;
+                    // Check if this is a JSON line
+                    if (trimmedLine.startsWith("{")) {
+                        // Save raw JSON if enabled
+                        if (jsonLogPath) {
+                            try {
+                                appendFileSync(jsonLogPath, trimmedLine + "\n");
+                            }
+                            catch {
+                                // Ignore write errors
+                            }
+                        }
+                        // Parse and display clean text
+                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        if (text) {
+                            process.stdout.write(text);
+                        }
+                    }
+                    else {
+                        // Non-JSON line - display as-is (might be status messages, errors, etc.)
+                        process.stdout.write(trimmedLine + "\n");
+                    }
+                }
+            });
+            proc.on("close", (code) => {
+                // Process any remaining buffered content
+                if (lineBuffer.trim()) {
+                    const trimmedLine = lineBuffer.trim();
+                    if (trimmedLine.startsWith("{")) {
+                        if (jsonLogPath) {
+                            try {
+                                appendFileSync(jsonLogPath, trimmedLine + "\n");
+                            }
+                            catch {
+                                // Ignore write errors
+                            }
+                        }
+                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        if (text) {
+                            process.stdout.write(text);
+                        }
+                    }
+                    else {
+                        // Non-JSON remaining content
+                        process.stdout.write(trimmedLine + "\n");
+                    }
+                }
+                // Ensure final newline
+                process.stdout.write("\n");
+                if (code !== 0) {
+                    console.error(`\n${cliConfig.command} exited with code ${code}`);
+                }
+                resolve();
+            });
+            proc.on("error", (err) => {
+                reject(new Error(`Failed to start ${cliConfig.command}: ${err.message}`));
+            });
+        }
+        else {
+            // Standard mode: pass through all I/O
+            const proc = spawn(cliConfig.command, cliArgs, {
+                stdio: "inherit",
+            });
+            proc.on("close", (code) => {
+                if (code !== 0) {
+                    console.error(`\n${cliConfig.command} exited with code ${code}`);
+                }
+                resolve();
+            });
+            proc.on("error", (err) => {
+                reject(new Error(`Failed to start ${cliConfig.command}: ${err.message}`));
+            });
+        }
     });
 }

package/dist/commands/run.js

@@ -1,9 +1,140 @@
 import { spawn } from "child_process";
-import { existsSync, readFileSync, writeFileSync, unlinkSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, unlinkSync, appendFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { checkFilesExist, loadConfig, loadPrompt, getPaths, getCliConfig, requireContainer } from "../utils/config.js";
 import { resolvePromptVariables } from "../templates/prompts.js";
 import { validatePrd, smartMerge, readPrdFile, writePrd, expandPrdFileReferences } from "../utils/prd-validator.js";
+/**
+ * Parses a stream-json line and extracts displayable text.
+ * Formats output similar to Claude Code's normal terminal display.
+ */
+function parseStreamJsonLine(line, debug = false) {
+    try {
+        const json = JSON.parse(line);
+        if (debug && json.type) {
+            process.stderr.write(`[stream-json] type: ${json.type}\n`);
+        }
+        // Handle Claude Code CLI stream-json events
+        const type = json.type;
+        switch (type) {
+            // === Text Content ===
+            case "content_block_delta":
+                // Incremental text updates - the main streaming content
+                if (json.delta?.type === "text_delta") {
+                    return json.delta.text || "";
+                }
+                // Tool input being streamed
+                if (json.delta?.type === "input_json_delta") {
+                    return ""; // Don't show partial JSON, wait for complete tool call
+                }
+                return json.delta?.text || "";
+            case "text":
+                return json.text || "";
+            // === Tool Use ===
+            case "content_block_start":
+                if (json.content_block?.type === "tool_use") {
+                    const toolName = json.content_block?.name || "unknown";
+                    return `\n── Tool: ${toolName} ──\n`;
+                }
+                if (json.content_block?.type === "text") {
+                    return json.content_block?.text || "";
+                }
+                return "";
+            case "content_block_stop":
+                // End of a content block - add newline after tool use
+                return "";
+            // === Tool Results ===
+            case "tool_result":
+                const toolOutput = json.content || json.output || "";
+                const truncated = typeof toolOutput === "string" && toolOutput.length > 500
+                    ? toolOutput.substring(0, 500) + "... (truncated)"
+                    : toolOutput;
+                return `\n── Tool Result ──\n${typeof truncated === "string" ? truncated : JSON.stringify(truncated, null, 2)}\n`;
+            // === Assistant Messages ===
+            case "assistant":
+                const contents = json.message?.content || json.content || [];
+                let output = "";
+                for (const block of contents) {
+                    if (block.type === "text") {
+                        output += block.text || "";
+                    }
+                    else if (block.type === "tool_use") {
+                        output += `\n── Tool: ${block.name} ──\n`;
+                        if (block.input) {
+                            output += JSON.stringify(block.input, null, 2) + "\n";
+                        }
+                    }
+                }
+                return output;
+            case "message_start":
+                // Beginning of a new message
+                return "\n";
+            case "message_delta":
+                // Message completion info (stop_reason, usage)
+                if (json.delta?.stop_reason) {
+                    return `\n[${json.delta.stop_reason}]\n`;
+                }
+                return "";
+            case "message_stop":
+                return "\n";
+            // === System/User Events ===
+            case "system":
+                if (json.message) {
+                    return `[System] ${json.message}\n`;
+                }
+                return "";
+            case "user":
+                // User message echo - usually not needed to display
+                return "";
+            // === Results and Errors ===
+            case "result":
+                if (json.result !== undefined) {
+                    return `\n── Result ──\n${JSON.stringify(json.result, null, 2)}\n`;
+                }
+                return "";
+            case "error":
+                const errMsg = json.error?.message || JSON.stringify(json.error);
+                return `\n[Error] ${errMsg}\n`;
+            // === File Operations (Claude Code specific) ===
+            case "file_edit":
+            case "file_write":
+                const filePath = json.path || json.file || "unknown";
+                return `\n── Writing: ${filePath} ──\n`;
+            case "file_read":
+                const readPath = json.path || json.file || "unknown";
+                return `── Reading: ${readPath} ──\n`;
+            case "bash":
+            case "command":
+                const cmd = json.command || json.content || "";
+                return `\n── Running: ${cmd} ──\n`;
+            case "bash_output":
+            case "command_output":
+                const cmdOutput = json.output || json.content || "";
+                return cmdOutput + "\n";
+            default:
+                // Fallback: check for common text fields
+                if (json.text)
+                    return json.text;
+                if (json.content && typeof json.content === "string")
+                    return json.content;
+                if (json.message && typeof json.message === "string")
+                    return json.message;
+                if (json.output && typeof json.output === "string")
+                    return json.output;
+                if (debug) {
+                    process.stderr.write(`[stream-json] unhandled type: ${type}, keys: ${Object.keys(json).join(", ")}\n`);
+                }
+                return "";
+        }
+    }
+    catch (e) {
+        // Not valid JSON
+        if (debug) {
+            process.stderr.write(`[stream-json] parse error: ${e}\n`);
+        }
+        return "";
+    }
+}
 const CATEGORIES = ["ui", "feature", "bugfix", "setup", "development", "testing", "docs"];
 /**
  * Creates a filtered PRD file containing only incomplete items (passes: false).
@@ -71,9 +202,11 @@ function syncPassesFromTasks(tasksPath, prdPath) {
         return 0;
     }
 }
-async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model) {
+async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model, streamJson) {
     return new Promise((resolve, reject) => {
         let output = "";
+        let jsonLogPath;
+        let lineBuffer = ""; // Buffer for incomplete JSON lines
         // Build CLI arguments: config args + yolo args + model args + prompt args
         const cliArgs = [
             ...(cliConfig.args ?? []),
@@ -84,6 +217,19 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
             const yoloArgs = cliConfig.yoloArgs ?? ["--dangerously-skip-permissions"];
             cliArgs.push(...yoloArgs);
         }
+        // Add stream-json output format if enabled
+        if (streamJson?.enabled) {
+            cliArgs.push("--output-format", "stream-json", "--verbose", "--print");
+            // Setup JSON log file if saving raw JSON
+            if (streamJson.saveRawJson) {
+                const outputDir = join(process.cwd(), streamJson.outputDir);
+                if (!existsSync(outputDir)) {
+                    mkdirSync(outputDir, { recursive: true });
+                }
+                const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+                jsonLogPath = join(outputDir, `ralph-run-${timestamp}.jsonl`);
+            }
+        }
         // Add model args if model is specified
         if (model && cliConfig.modelArgs) {
             cliArgs.push(...cliConfig.modelArgs, model);
@@ -95,16 +241,85 @@ async function runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig
         cliArgs.push(...promptArgs, promptValue);
         if (debug) {
             console.log(`[debug] ${cliConfig.command} ${cliArgs.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}\n`);
+            if (jsonLogPath) {
+                console.log(`[debug] Saving raw JSON to: ${jsonLogPath}\n`);
+            }
         }
         const proc = spawn(cliConfig.command, cliArgs, {
             stdio: ["inherit", "pipe", "inherit"],
         });
         proc.stdout.on("data", (data) => {
             const chunk = data.toString();
-            output += chunk;
-            process.stdout.write(chunk);
+            if (streamJson?.enabled) {
+                // Process stream-json output: parse JSON and display clean text
+                lineBuffer += chunk;
+                const lines = lineBuffer.split("\n");
+                // Keep the last incomplete line in the buffer
+                lineBuffer = lines.pop() || "";
+                for (const line of lines) {
+                    const trimmedLine = line.trim();
+                    if (!trimmedLine)
+                        continue;
+                    // Check if this is a JSON line
+                    if (trimmedLine.startsWith("{")) {
+                        // Save raw JSON if enabled
+                        if (jsonLogPath) {
+                            try {
+                                appendFileSync(jsonLogPath, trimmedLine + "\n");
+                            }
+                            catch {
+                                // Ignore write errors
+                            }
+                        }
+                        // Parse and display clean text
+                        const text = parseStreamJsonLine(trimmedLine, debug);
+                        if (text) {
+                            process.stdout.write(text);
+                            output += text; // Accumulate parsed text for completion detection
+                        }
+                    }
+                    else {
+                        // Non-JSON line - display as-is (might be status messages, errors, etc.)
+                        process.stdout.write(trimmedLine + "\n");
+                        output += trimmedLine + "\n";
+                    }
+                }
+            }
+            else {
+                // Standard output: pass through as-is
+                output += chunk;
+                process.stdout.write(chunk);
+            }
         });
         proc.on("close", (code) => {
+            // Process any remaining buffered content
+            if (streamJson?.enabled && lineBuffer.trim()) {
+                const trimmedLine = lineBuffer.trim();
+                if (trimmedLine.startsWith("{")) {
+                    if (jsonLogPath) {
+                        try {
+                            appendFileSync(jsonLogPath, trimmedLine + "\n");
+                        }
+                        catch {
+                            // Ignore write errors
+                        }
+                    }
+                    const text = parseStreamJsonLine(trimmedLine, debug);
+                    if (text) {
+                        process.stdout.write(text);
+                        output += text;
+                    }
+                }
+                else {
+                    // Non-JSON remaining content
+                    process.stdout.write(trimmedLine + "\n");
+                    output += trimmedLine + "\n";
+                }
+            }
+            // Ensure final newline for clean output
+            if (streamJson?.enabled) {
+                process.stdout.write("\n");
+            }
             resolve({ exitCode: code ?? 0, output });
         });
         proc.on("error", (err) => {
@@ -265,6 +480,13 @@ export async function run(args) {
     });
     const paths = getPaths();
     const cliConfig = getCliConfig(config);
+    // Check if stream-json output is enabled
+    const streamJsonConfig = config.docker?.asciinema?.streamJson;
+    const streamJson = streamJsonConfig?.enabled ? {
+        enabled: true,
+        saveRawJson: streamJsonConfig.saveRawJson !== false, // default true
+        outputDir: config.docker?.asciinema?.outputDir || ".recordings",
+    } : undefined;
     // Progress tracking: stop only if no tasks complete after N iterations
     const MAX_ITERATIONS_WITHOUT_PROGRESS = 3;
     // Get requested iteration count (may be adjusted dynamically)
@@ -285,6 +507,12 @@ export async function run(args) {
     if (category) {
         console.log(`Filtering PRD items by category: ${category}`);
     }
+    if (streamJson?.enabled) {
+        console.log("Stream JSON output enabled - displaying formatted Claude output");
+        if (streamJson.saveRawJson) {
+            console.log(`Raw JSON logs will be saved to: ${streamJson.outputDir}/`);
+        }
+    }
     console.log();
     // Track temp file for cleanup
     let filteredPrdPath = null;
@@ -381,7 +609,7 @@ export async function run(args) {
                     break;
                 }
             }
-            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model);
+            const { exitCode, output } = await runIteration(prompt, paths, sandboxed, filteredPrdPath, cliConfig, debug, model, streamJson);
             // Sync any completed items from prd-tasks.json back to prd.json
             // This catches cases where the LLM updated prd-tasks.json instead of prd.json
             syncPassesFromTasks(filteredPrdPath, paths.prd);

package/dist/config/skills.json

@@ -0,0 +1,12 @@
+{
+  "skills": {
+    "swift": [
+      {
+        "name": "swift-main-naming",
+        "description": "Prevents naming files main.swift when using @main attribute",
+        "instructions": "IMPORTANT: In Swift, files containing the @main attribute MUST NOT be named main.swift.\n\nWhen the @main attribute is used (e.g., @main struct App), Swift automatically generates an entry point. If the file is also named main.swift, Swift treats it as having a manual entry point, causing a conflict.\n\nRULES:\n- Never name a file main.swift if it contains @main attribute\n- Use descriptive names like App.swift, MyApp.swift, or the actual type name\n- If you encounter a main.swift with @main, rename it to match the type (e.g., struct MyApp -> MyApp.swift)\n\nEXAMPLES:\n\nBAD:\n```\n// main.swift\n@main\nstruct App {\n    static func main() { ... }\n}\n```\n\nGOOD:\n```\n// App.swift\n@main\nstruct App {\n    static func main() { ... }\n}\n```",
+        "userInvocable": false
+      }
+    ]
+  }
+}

package/dist/templates/prompts.d.ts

@@ -48,9 +48,20 @@ export interface CliProviderConfig {
 interface CliProvidersJson {
     providers: Record<string, CliProviderConfig>;
 }
+export interface SkillDefinition {
+    name: string;
+    description: string;
+    instructions: string;
+    userInvocable?: boolean;
+}
+interface SkillsJson {
+    skills: Record<string, SkillDefinition[]>;
+}
 export declare function getLanguagesJson(): LanguagesJson;
 export declare function getCliProvidersJson(): CliProvidersJson;
 export declare function getCliProviders(): Record<string, CliProviderConfig>;
+export declare function getSkillsJson(): SkillsJson;
+export declare function getSkillsForLanguage(language: string): SkillDefinition[];
 export declare function getLanguages(): Record<string, LanguageConfig>;
 export declare const LANGUAGES: Record<string, LanguageConfig>;
 export declare function generatePromptTemplate(): string;

package/dist/templates/prompts.js

@@ -17,6 +17,12 @@ function loadCliProvidersConfig() {
     const content = readFileSync(configPath, "utf-8");
     return JSON.parse(content);
 }
+// Load skills from JSON config file
+function loadSkillsConfig() {
+    const configPath = join(__dirname, "..", "config", "skills.json");
+    const content = readFileSync(configPath, "utf-8");
+    return JSON.parse(content);
+}
 // Convert JSON config to the legacy format for compatibility
 function convertToLanguageConfig(config) {
     return {
@@ -31,6 +37,7 @@ function convertToLanguageConfig(config) {
 let _languagesCache = null;
 let _languagesJsonCache = null;
 let _cliProvidersCache = null;
+let _skillsCache = null;
 export function getLanguagesJson() {
     if (!_languagesJsonCache) {
         _languagesJsonCache = loadLanguagesConfig();
@@ -46,6 +53,16 @@ export function getCliProvidersJson() {
 export function getCliProviders() {
     return getCliProvidersJson().providers;
 }
+export function getSkillsJson() {
+    if (!_skillsCache) {
+        _skillsCache = loadSkillsConfig();
+    }
+    return _skillsCache;
+}
+export function getSkillsForLanguage(language) {
+    const skills = getSkillsJson().skills;
+    return skills[language] || [];
+}
 export function getLanguages() {
     if (!_languagesCache) {
         const json = getLanguagesJson();

package/dist/utils/config.d.ts

@@ -16,10 +16,15 @@ export interface SkillConfig {
     instructions: string;
     userInvocable?: boolean;
 }
+export interface StreamJsonConfig {
+    enabled: boolean;
+    saveRawJson?: boolean;
+}
 export interface AsciinemaConfig {
     enabled: boolean;
     autoRecord?: boolean;
     outputDir?: string;
+    streamJson?: StreamJsonConfig;
 }
 export interface RalphConfig {
     language: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralph-cli-sandboxed",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "AI-driven development automation CLI for Claude Code",
   "type": "module",
   "bin": {