ralph-cli-claude 0.1.1 → 0.1.5

package/README.md

@@ -140,6 +140,74 @@ Generates `ralph.sh` and `ralph-once.sh` in your project root.
 
 When all PRD items pass, Claude outputs `<promise>COMPLETE</promise>` and stops.
 
+## Security
+
+### Container Requirement
+
+**It is strongly recommended to run ralph inside a Docker container for security.** The Ralph Wiggum technique involves running an AI agent autonomously, which means granting it elevated permissions to execute code and modify files without manual approval for each action.
+
+### The `--dangerously-skip-permissions` Flag
+
+When running inside a container, ralph automatically passes the `--dangerously-skip-permissions` flag to Claude Code. This flag:
+
+- Allows Claude to execute commands and modify files without prompting for permission
+- Is **only** enabled when ralph detects it's running inside a container
+- Is required for autonomous operation (otherwise Claude would pause for approval on every action)
+
+**Warning:** The `--dangerously-skip-permissions` flag gives the AI agent full control over the environment. This is why container isolation is critical:
+
+- The container provides a sandbox boundary
+- Network access is restricted to essential services (GitHub, npm, Anthropic API)
+- Your host system remains protected even if something goes wrong
+
+### Container Detection
+
+Ralph detects container environments by checking:
+- `DEVCONTAINER` environment variable
+- Presence of `/.dockerenv` file
+- Container indicators in `/proc/1/cgroup`
+- `container` environment variable
+
+If you're running outside a container and need autonomous mode, use `ralph docker` to set up a safe sandbox environment first.
+
+## Development
+
+To contribute or test changes to ralph locally:
+
+```bash
+# Clone the repository
+git clone https://github.com/anthropics/ralph-cli-claude
+cd ralph-cli-claude
+
+# Install dependencies
+npm install
+
+# Run ralph in development mode (without building)
+npm run dev -- <args>
+
+# Examples:
+npm run dev -- --version
+npm run dev -- prd list
+npm run dev -- once
+```
+
+The `npm run dev -- <args>` command runs ralph directly from TypeScript source using `tsx`, allowing you to test changes without rebuilding.
+
+### Platform-Specific Dependencies
+
+The `node_modules` folder contains platform-specific binaries (e.g., esbuild). If you switch between running on your host machine and inside a Docker/Podman container, you'll need to reinstall dependencies:
+
+```bash
+# When switching environments (host <-> container)
+rm -rf node_modules && npm install
+```
+
+Alternatively, when mounting your project into a container, use a separate volume for node_modules to keep host and container dependencies isolated:
+
+```bash
+podman run -v $(pwd):/workspace -v /workspace/node_modules your-image
+```
+
 ## Requirements
 
 - Node.js 18+

package/dist/commands/docker.js

@@ -24,8 +24,9 @@ RUN apt-get update && apt-get install -y \\
 RUN pip3 install --break-system-packages mypy pytest
 `,
     go: `
-# Install Go
-RUN curl -fsSL https://go.dev/dl/go1.22.0.linux-amd64.tar.gz | tar -C /usr/local -xzf -
+# Install Go (architecture-aware)
+RUN ARCH=$(dpkg --print-architecture) && \\
+    curl -fsSL "https://go.dev/dl/go1.22.0.linux-\${ARCH}.tar.gz" | tar -C /usr/local -xzf -
 ENV PATH="/usr/local/go/bin:/home/node/go/bin:$PATH"
 ENV GOPATH="/home/node/go"
 `,
@@ -38,8 +39,51 @@ ENV PATH="/home/node/.cargo/bin:$PATH"
 # Custom language - add your dependencies here
 `,
 };
-function generateDockerfile(language) {
-    const languageSnippet = LANGUAGE_SNIPPETS[language] || LANGUAGE_SNIPPETS.none;
+// Java snippet generator (supports configurable Java version)
+function getJavaSnippet(javaVersion = 17) {
+    return `
+# Install Java ${javaVersion} and Maven
+RUN apt-get update && apt-get install -y \\
+    openjdk-${javaVersion}-jdk \\
+    maven \\
+    && rm -rf /var/lib/apt/lists/* \\
+    && ln -s /usr/lib/jvm/java-${javaVersion}-openjdk-$(dpkg --print-architecture) /usr/lib/jvm/java-${javaVersion}-openjdk
+ENV JAVA_HOME="/usr/lib/jvm/java-${javaVersion}-openjdk"
+`;
+}
+// Kotlin snippet generator (supports configurable Java version)
+function getKotlinSnippet(javaVersion = 17) {
+    return `
+# Install Kotlin and Gradle (Java ${javaVersion})
+RUN apt-get update && apt-get install -y \\
+    openjdk-${javaVersion}-jdk \\
+    && rm -rf /var/lib/apt/lists/* \\
+    && ln -s /usr/lib/jvm/java-${javaVersion}-openjdk-$(dpkg --print-architecture) /usr/lib/jvm/java-${javaVersion}-openjdk
+ENV JAVA_HOME="/usr/lib/jvm/java-${javaVersion}-openjdk"
+# Install Gradle
+RUN curl -fsSL https://services.gradle.org/distributions/gradle-8.5-bin.zip -o /tmp/gradle.zip && \\
+    unzip -d /opt /tmp/gradle.zip && \\
+    rm /tmp/gradle.zip
+ENV PATH="/opt/gradle-8.5/bin:$PATH"
+# Install Kotlin compiler
+RUN curl -fsSL https://github.com/JetBrains/kotlin/releases/download/v1.9.22/kotlin-compiler-1.9.22.zip -o /tmp/kotlin.zip && \\
+    unzip -d /opt /tmp/kotlin.zip && \\
+    rm /tmp/kotlin.zip
+ENV PATH="/opt/kotlinc/bin:$PATH"
+`;
+}
+// Get language snippet, with special handling for Java/Kotlin
+function getLanguageSnippet(language, javaVersion) {
+    if (language === "java") {
+        return getJavaSnippet(javaVersion);
+    }
+    if (language === "kotlin") {
+        return getKotlinSnippet(javaVersion);
+    }
+    return LANGUAGE_SNIPPETS[language] || LANGUAGE_SNIPPETS.none;
+}
+function generateDockerfile(language, javaVersion) {
+    const languageSnippet = getLanguageSnippet(language, javaVersion);
     return `# Ralph CLI Sandbox Environment
 # Based on Claude Code devcontainer
 # Generated by ralph-cli
@@ -91,7 +135,22 @@ RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/download/
 RUN cp -r /root/.oh-my-zsh /home/node/.oh-my-zsh && chown -R node:node /home/node/.oh-my-zsh && \\
     cp /root/.zshrc /home/node/.zshrc && chown node:node /home/node/.zshrc && \\
     sed -i 's|/root/.oh-my-zsh|/home/node/.oh-my-zsh|g' /home/node/.zshrc && \\
-    echo 'PROMPT="%K{yellow}%F{black}[ralph]%f%k%K{yellow}%F{black}%d%f%k\\$ "' >> /home/node/.zshrc
+    echo 'PROMPT="%K{yellow}%F{black}[ralph]%f%k%K{yellow}%F{black}%d%f%k\\$ "' >> /home/node/.zshrc && \\
+    echo '' >> /home/node/.zshrc && \\
+    echo '# Ralph ASCII art banner' >> /home/node/.zshrc && \\
+    echo 'if [ -z "$RALPH_BANNER_SHOWN" ]; then' >> /home/node/.zshrc && \\
+    echo '  export RALPH_BANNER_SHOWN=1' >> /home/node/.zshrc && \\
+    echo '  echo ""' >> /home/node/.zshrc && \\
+    echo '  echo " ____      _    _     ____  _   _ "' >> /home/node/.zshrc && \\
+    echo '  echo "|  _ \\\\    / \\\\  | |   |  _ \\\\| | | |"' >> /home/node/.zshrc && \\
+    echo '  echo "| |_) |  / _ \\\\ | |   | |_) | |_| |"' >> /home/node/.zshrc && \\
+    echo '  echo "|  _ <  / ___ \\\\| |___|  __/|  _  |"' >> /home/node/.zshrc && \\
+    echo '  echo "|_| \\\\_\\\\/_/   \\\\_\\\\_____|_|   |_| |_|"' >> /home/node/.zshrc && \\
+    echo '  echo ""' >> /home/node/.zshrc && \\
+    echo '  RALPH_VERSION=$(ralph --version 2>/dev/null | head -1 || echo "unknown")' >> /home/node/.zshrc && \\
+    echo '  echo "CLI - Version $RALPH_VERSION"' >> /home/node/.zshrc && \\
+    echo '  echo ""' >> /home/node/.zshrc && \\
+    echo 'fi' >> /home/node/.zshrc
 
 # Install Claude Code CLI
 RUN npm install -g @anthropic-ai/claude-code@\${CLAUDE_CODE_VERSION}
@@ -246,7 +305,7 @@ dist
 .git
 *.log
 `;
-async function generateFiles(ralphDir, language, imageName, force = false) {
+async function generateFiles(ralphDir, language, imageName, force = false, javaVersion) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
     // Create docker directory
     if (!existsSync(dockerDir)) {
@@ -254,7 +313,7 @@ async function generateFiles(ralphDir, language, imageName, force = false) {
         console.log(`Created ${DOCKER_DIR}/`);
     }
     const files = [
-        { name: "Dockerfile", content: generateDockerfile(language) },
+        { name: "Dockerfile", content: generateDockerfile(language, javaVersion) },
         { name: "init-firewall.sh", content: FIREWALL_SCRIPT },
         { name: "docker-compose.yml", content: generateDockerCompose(imageName) },
         { name: ".dockerignore", content: DOCKERIGNORE },
@@ -281,9 +340,10 @@ async function buildImage(ralphDir) {
         console.error("Dockerfile not found. Run 'ralph docker' first.");
         process.exit(1);
     }
-    console.log("Building Docker image...\n");
+    console.log("Building Docker image (fetching latest Claude Code)...\n");
     return new Promise((resolve, reject) => {
-        const proc = spawn("docker", ["compose", "build"], {
+        // Use --no-cache and --pull to ensure we always get the latest Claude Code version
+        const proc = spawn("docker", ["compose", "build", "--no-cache", "--pull"], {
             cwd: dockerDir,
             stdio: "inherit",
         });
@@ -301,11 +361,40 @@ async function buildImage(ralphDir) {
         });
     });
 }
-async function runContainer(ralphDir) {
+async function imageExists(imageName) {
+    return new Promise((resolve) => {
+        const proc = spawn("docker", ["images", "-q", imageName], {
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let output = "";
+        proc.stdout.on("data", (data) => {
+            output += data.toString();
+        });
+        proc.on("close", () => {
+            // If output is non-empty, image exists
+            resolve(output.trim().length > 0);
+        });
+        proc.on("error", () => {
+            resolve(false);
+        });
+    });
+}
+async function runContainer(ralphDir, imageName, language, javaVersion) {
     const dockerDir = join(ralphDir, DOCKER_DIR);
-    if (!existsSync(join(dockerDir, "Dockerfile"))) {
-        console.error("Dockerfile not found. Run 'ralph docker' first.");
-        process.exit(1);
+    const dockerfileExists = existsSync(join(dockerDir, "Dockerfile"));
+    const hasImage = await imageExists(imageName);
+    // Auto-init and build if docker folder or image doesn't exist
+    if (!dockerfileExists || !hasImage) {
+        if (!dockerfileExists) {
+            console.log("Docker folder not found. Initializing docker setup...\n");
+            await generateFiles(ralphDir, language, imageName, true, javaVersion);
+            console.log("");
+        }
+        if (!hasImage) {
+            console.log("Docker image not found. Building image...\n");
+            await buildImage(ralphDir);
+            console.log("");
+        }
     }
     console.log("Starting Docker container...\n");
     return new Promise((resolve, reject) => {
@@ -326,7 +415,167 @@ async function runContainer(ralphDir) {
         });
     });
 }
+async function cleanImage(imageName, ralphDir) {
+    const dockerDir = join(ralphDir, DOCKER_DIR);
+    console.log(`Cleaning Docker image: ${imageName}...\n`);
+    // First, stop any running containers via docker compose
+    if (existsSync(join(dockerDir, "docker-compose.yml"))) {
+        // Stop running containers first
+        await new Promise((resolve) => {
+            const proc = spawn("docker", ["compose", "stop", "--timeout", "5"], {
+                cwd: dockerDir,
+                stdio: "inherit",
+            });
+            proc.on("close", () => {
+                resolve();
+            });
+            proc.on("error", () => {
+                resolve();
+            });
+        });
+        // Remove containers, volumes, networks, and local images
+        await new Promise((resolve) => {
+            const proc = spawn("docker", ["compose", "down", "--rmi", "local", "-v", "--remove-orphans", "--timeout", "5"], {
+                cwd: dockerDir,
+                stdio: "inherit",
+            });
+            proc.on("close", () => {
+                // Continue regardless of exit code (image may not exist)
+                resolve();
+            });
+            proc.on("error", () => {
+                resolve();
+            });
+        });
+    }
+    // Find and forcibly remove any containers using volumes with our image name pattern
+    // This handles orphaned containers from previous runs or pods
+    const volumePattern = `docker_${imageName}`;
+    await new Promise((resolve) => {
+        // List all containers (including stopped) and filter by volume name pattern
+        const proc = spawn("docker", ["ps", "-aq", "--filter", `volume=${volumePattern}`], {
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let output = "";
+        proc.stdout.on("data", (data) => {
+            output += data.toString();
+        });
+        proc.on("close", async () => {
+            const containerIds = output.trim().split("\n").filter((id) => id.length > 0);
+            if (containerIds.length > 0) {
+                // Force remove these containers
+                await new Promise((innerResolve) => {
+                    const rmProc = spawn("docker", ["rm", "-f", ...containerIds], {
+                        stdio: "inherit",
+                    });
+                    rmProc.on("close", () => innerResolve());
+                    rmProc.on("error", () => innerResolve());
+                });
+            }
+            resolve();
+        });
+        proc.on("error", () => {
+            resolve();
+        });
+    });
+    // Also try to remove the image directly (in case it was built outside compose)
+    await new Promise((resolve) => {
+        const proc = spawn("docker", ["rmi", "-f", imageName], {
+            stdio: "inherit",
+        });
+        proc.on("close", () => {
+            resolve();
+        });
+        proc.on("error", () => {
+            resolve();
+        });
+    });
+    // Clean up volumes matching our pattern
+    await new Promise((resolve) => {
+        // List volumes matching our pattern
+        const proc = spawn("docker", ["volume", "ls", "-q", "--filter", `name=${volumePattern}`], {
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let output = "";
+        proc.stdout.on("data", (data) => {
+            output += data.toString();
+        });
+        proc.on("close", async () => {
+            const volumeNames = output.trim().split("\n").filter((name) => name.length > 0);
+            if (volumeNames.length > 0) {
+                // Force remove these volumes
+                await new Promise((innerResolve) => {
+                    const rmProc = spawn("docker", ["volume", "rm", "-f", ...volumeNames], {
+                        stdio: "inherit",
+                    });
+                    rmProc.on("close", () => innerResolve());
+                    rmProc.on("error", () => innerResolve());
+                });
+            }
+            resolve();
+        });
+        proc.on("error", () => {
+            resolve();
+        });
+    });
+    // Also try removing the simple volume name pattern
+    const volumeName = `${imageName}-history`;
+    await new Promise((resolve) => {
+        const proc = spawn("docker", ["volume", "rm", "-f", volumeName], {
+            stdio: "inherit",
+        });
+        proc.on("close", () => {
+            resolve();
+        });
+        proc.on("error", () => {
+            resolve();
+        });
+    });
+    // For Podman: clean up any orphaned pods matching our pattern
+    await new Promise((resolve) => {
+        const proc = spawn("docker", ["pod", "ls", "-q", "--filter", `name=docker`], {
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let output = "";
+        proc.stdout.on("data", (data) => {
+            output += data.toString();
+        });
+        proc.on("close", async () => {
+            const podIds = output.trim().split("\n").filter((id) => id.length > 0);
+            if (podIds.length > 0) {
+                // Force remove these pods (this also removes their containers)
+                await new Promise((innerResolve) => {
+                    const rmProc = spawn("docker", ["pod", "rm", "-f", ...podIds], {
+                        stdio: "inherit",
+                    });
+                    rmProc.on("close", () => innerResolve());
+                    rmProc.on("error", () => innerResolve());
+                });
+            }
+            resolve();
+        });
+        proc.on("error", () => {
+            // docker pod command doesn't exist (not Podman) - ignore
+            resolve();
+        });
+    });
+    // Clean up the docker_default network if it exists and is empty
+    await new Promise((resolve) => {
+        const proc = spawn("docker", ["network", "rm", "docker_default"], {
+            stdio: "inherit",
+        });
+        proc.on("close", () => {
+            resolve();
+        });
+        proc.on("error", () => {
+            resolve();
+        });
+    });
+    console.log("\nDocker image and associated resources cleaned.");
+    console.log("Run 'ralph docker --build' to rebuild the image.");
+}
 export async function docker(args) {
+    const hasFlag = (flag) => args.includes(flag);
     const flag = args[0];
     // Show help without requiring init
     if (flag === "--help" || flag === "-h") {
@@ -336,8 +585,10 @@ ralph docker - Generate and manage Docker sandbox environment
 USAGE:
   ralph docker              Generate Dockerfile and scripts
   ralph docker -y           Generate files, overwrite without prompting
-  ralph docker --build      Build the Docker image
-  ralph docker --run        Run container with project mounted
+  ralph docker --build      Build image (always fetches latest Claude Code)
+  ralph docker --build --clean  Clean existing image and rebuild from scratch
+  ralph docker --run        Run container (auto-init and build if needed)
+  ralph docker --clean      Remove Docker image and associated resources
 
 FILES GENERATED:
   .ralph/docker/
@@ -353,7 +604,9 @@ AUTHENTICATION:
 EXAMPLES:
   ralph docker                      # Generate files
   ralph docker --build              # Build image
+  ralph docker --build --clean      # Clean and rebuild from scratch
   ralph docker --run                # Start interactive shell
+  ralph docker --clean              # Remove image and volumes
 
   # Or use docker compose directly:
   cd .ralph/docker && docker compose run --rm ralph
@@ -383,17 +636,29 @@ INSTALLING PACKAGES (works with Docker & Podman):
     const config = loadConfig();
     // Get image name from config or generate default
     const imageName = config.imageName || `ralph-${basename(process.cwd()).toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
-    if (flag === "--build") {
+    // Handle --build --clean combination: clean first, then build
+    if (hasFlag("--build") && hasFlag("--clean")) {
+        await cleanImage(imageName, ralphDir);
+        console.log(""); // Add spacing between clean and build output
         await buildImage(ralphDir);
     }
-    else if (flag === "--run") {
-        await runContainer(ralphDir);
+    else if (hasFlag("--build")) {
+        await buildImage(ralphDir);
+    }
+    else if (hasFlag("--run")) {
+        await runContainer(ralphDir, imageName, config.language, config.javaVersion);
+    }
+    else if (hasFlag("--clean")) {
+        await cleanImage(imageName, ralphDir);
     }
     else {
         const force = flag === "-y" || flag === "--yes";
         console.log(`Generating Docker files for: ${config.language}`);
+        if ((config.language === "java" || config.language === "kotlin") && config.javaVersion) {
+            console.log(`Java version: ${config.javaVersion}`);
+        }
         console.log(`Image name: ${imageName}\n`);
-        await generateFiles(ralphDir, config.language, imageName, force);
+        await generateFiles(ralphDir, config.language, imageName, force, config.javaVersion);
         console.log(`
 Docker files generated in .ralph/docker/
 

package/dist/commands/help.js

@@ -5,38 +5,65 @@ USAGE:
   ralph <command> [options]
 
 COMMANDS:
-  init              Initialize ralph in current project
+  init [opts]       Initialize ralph in current project
   once              Run a single automation iteration
-  run <n>           Run n automation iterations
+  run <n> [opts]    Run n automation iterations
   prd <subcommand>  Manage PRD entries
+  prompt [opts]     Display resolved prompt (for testing in Claude Code)
   scripts           Generate shell scripts (for sandboxed environments)
   docker            Generate Docker sandbox environment
   help              Show this help message
 
+INIT OPTIONS:
+  --tech-stack, -t           Enable technology stack selection prompt
+
+RUN OPTIONS:
+  --all, -a                  Run until all tasks are complete, showing progress
+  --loop, -l                 Run continuously, waiting for new items when complete
+  --category, -c <category>  Filter PRD items by category
+                             Valid: ui, feature, bugfix, setup, development, testing, docs
+
 PRD SUBCOMMANDS:
   prd add           Add a new PRD entry (interactive)
-  prd list          List all PRD entries
+  prd list [opts]   List all PRD entries
   prd status        Show PRD completion status
   prd toggle <n>    Toggle passes status for entry n
   prd toggle --all  Toggle all PRD entries
+  prd clean         Remove all passing entries from the PRD
+
+PRD LIST OPTIONS:
+  --category, -c <category>  Filter PRD items by category
+                             Valid: ui, feature, bugfix, setup, development, testing, docs
 
 EXAMPLES:
-  ralph init                 # Initialize ralph for your project
+  ralph init                 # Initialize ralph (language selection only)
+  ralph init --tech-stack    # Initialize with technology stack selection
   ralph once                 # Run single iteration
   ralph run 5                # Run 5 iterations
+  ralph run --all            # Run until all tasks complete (shows progress)
+  ralph run --all -c feature # Complete all feature tasks only
+  ralph run --loop           # Run continuously until interrupted
+  ralph run --loop -c feature  # Loop mode, only feature items
+  ralph run 5 --category feature  # Run 5 iterations, only feature items
+  ralph run 3 -c bugfix      # Run 3 iterations, only bugfix items
   ralph prd add              # Add new PRD entry
   ralph prd list             # Show all entries
+  ralph prd list -c feature  # Show only feature entries
   ralph prd status           # Show completion summary
+  ralph prompt               # Display resolved prompt
+  ralph prompt --raw         # Display template with $variables
   ralph scripts              # Generate ralph.sh and ralph-once.sh
   ralph docker               # Generate Dockerfile for sandboxed env
   ralph docker --build       # Build Docker image
-  ralph docker --run         # Run container interactively
+  ralph docker --build --clean  # Clean and rebuild from scratch
+  ralph docker --run         # Run container (auto-init/build if needed)
+  ralph docker --clean       # Remove image and volumes
 
 CONFIGURATION:
   After running 'ralph init', you'll have:
   .ralph/
-  ├── config.json      Project configuration
-  ├── prompt.md        Shared prompt template
+  ├── config.json      Project configuration (language, commands, javaVersion)
+  ├── prompt.md        Prompt template with $variables ($language, $checkCommand, etc.)
   ├── prd.json         Product requirements document
   └── progress.txt     Progress tracking file
 `;

package/dist/commands/init.d.ts

@@ -1 +1 @@
-export declare function init(_args: string[]): Promise<void>;
+export declare function init(args: string[]): Promise<void>;

package/dist/commands/init.js

@@ -1,15 +1,25 @@
-import { existsSync, writeFileSync, mkdirSync } from "fs";
-import { join, basename } from "path";
-import { LANGUAGES, generatePrompt, DEFAULT_PRD, DEFAULT_PROGRESS } from "../templates/prompts.js";
-import { promptSelect, promptConfirm, promptInput } from "../utils/prompt.js";
+import { existsSync, writeFileSync, mkdirSync, copyFileSync } from "fs";
+import { join, basename, dirname } from "path";
+import { fileURLToPath } from "url";
+import { LANGUAGES, generatePromptTemplate, DEFAULT_PRD, DEFAULT_PROGRESS } from "../templates/prompts.js";
+import { promptSelect, promptConfirm, promptInput, promptMultiSelect } from "../utils/prompt.js";
+// Get package root directory (works for both dev and installed package)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = join(__dirname, "..", ".."); // dist/commands -> dist -> package root
 const RALPH_DIR = ".ralph";
 const CONFIG_FILE = "config.json";
 const PROMPT_FILE = "prompt.md";
 const PRD_FILE = "prd.json";
 const PROGRESS_FILE = "progress.txt";
-export async function init(_args) {
+const PRD_GUIDE_FILE = "HOW-TO-WRITE-PRDs.md";
+function hasFlag(args, ...flags) {
+    return args.some(arg => flags.includes(arg));
+}
+export async function init(args) {
     const cwd = process.cwd();
     const ralphDir = join(cwd, RALPH_DIR);
+    const showTechStack = hasFlag(args, "--tech-stack", "-t");
     console.log("Initializing ralph in current directory...\n");
     // Check for existing .ralph directory
     if (existsSync(ralphDir)) {
@@ -30,6 +40,24 @@ export async function init(_args) {
     const selectedIndex = languageNames.indexOf(selectedName);
     const selectedKey = languageKeys[selectedIndex];
     const config = LANGUAGES[selectedKey];
+    // Select technology stack if available (only when --tech-stack flag is provided)
+    let selectedTechnologies = [];
+    if (showTechStack && config.technologies && config.technologies.length > 0) {
+        const techOptions = config.technologies.map(t => `${t.name} - ${t.description}`);
+        const techNames = config.technologies.map(t => t.name);
+        selectedTechnologies = await promptMultiSelect("Select your technology stack (select multiple or add custom):", techOptions);
+        // Convert display names back to just technology names for predefined options
+        selectedTechnologies = selectedTechnologies.map(sel => {
+            const idx = techOptions.indexOf(sel);
+            return idx >= 0 ? techNames[idx] : sel;
+        });
+        if (selectedTechnologies.length > 0) {
+            console.log(`\nSelected technologies: ${selectedTechnologies.join(", ")}`);
+        }
+        else {
+            console.log("\nNo technologies selected.");
+        }
+    }
     // Allow custom commands
     let checkCommand = config.checkCommand;
     let testCommand = config.testCommand;
@@ -52,11 +80,15 @@ export async function init(_args) {
         testCommand: finalConfig.testCommand,
         imageName,
     };
+    // Add technologies if any were selected
+    if (selectedTechnologies.length > 0) {
+        configData.technologies = selectedTechnologies;
+    }
     const configPath = join(ralphDir, CONFIG_FILE);
     writeFileSync(configPath, JSON.stringify(configData, null, 2) + "\n");
     console.log(`\nCreated ${RALPH_DIR}/${CONFIG_FILE}`);
-    // Write prompt file (ask if exists)
-    const prompt = generatePrompt(finalConfig);
+    // Write prompt file (ask if exists) - uses template with $variables
+    const prompt = generatePromptTemplate();
     const promptPath = join(ralphDir, PROMPT_FILE);
     if (existsSync(promptPath)) {
         const overwritePrompt = await promptConfirm(`${RALPH_DIR}/${PROMPT_FILE} already exists. Overwrite?`);
@@ -90,9 +122,22 @@ export async function init(_args) {
     else {
         console.log(`Skipped ${RALPH_DIR}/${PROGRESS_FILE} (already exists)`);
     }
+    // Copy PRD guide file from package if not exists
+    const prdGuidePath = join(ralphDir, PRD_GUIDE_FILE);
+    if (!existsSync(prdGuidePath)) {
+        const sourcePath = join(PACKAGE_ROOT, "docs", PRD_GUIDE_FILE);
+        if (existsSync(sourcePath)) {
+            copyFileSync(sourcePath, prdGuidePath);
+            console.log(`Created ${RALPH_DIR}/${PRD_GUIDE_FILE}`);
+        }
+    }
+    else {
+        console.log(`Skipped ${RALPH_DIR}/${PRD_GUIDE_FILE} (already exists)`);
+    }
     console.log("\nRalph initialized successfully!");
     console.log("\nNext steps:");
-    console.log("  1. Edit .ralph/prd.json to add your project requirements");
-    console.log("  2. Run 'ralph once' to start the first iteration");
-    console.log("  3. Or run 'ralph run 5' for 5 automated iterations");
+    console.log("  1. Read .ralph/HOW-TO-WRITE-PRDs.md for guidance on writing PRDs");
+    console.log("  2. Edit .ralph/prd.json to add your project requirements");
+    console.log("  3. Run 'ralph once' to start the first iteration");
+    console.log("  4. Or run 'ralph run 5' for 5 automated iterations");
 }

package/dist/commands/once.js

@@ -1,8 +1,16 @@
 import { spawn } from "child_process";
-import { checkFilesExist, loadPrompt, getPaths } from "../utils/config.js";
+import { checkFilesExist, loadConfig, loadPrompt, getPaths } from "../utils/config.js";
+import { resolvePromptVariables } from "../templates/prompts.js";
 export async function once(_args) {
     checkFilesExist();
-    const prompt = loadPrompt();
+    const config = loadConfig();
+    const template = loadPrompt();
+    const prompt = resolvePromptVariables(template, {
+        language: config.language,
+        checkCommand: config.checkCommand,
+        testCommand: config.testCommand,
+        technologies: config.technologies,
+    });
     const paths = getPaths();
     console.log("Starting single ralph iteration...\n");
     return new Promise((resolve, reject) => {