ralph-cli-sandboxed 0.2.8 → 0.2.9

package/README.md

@@ -196,6 +196,36 @@ Ralph can be configured to use different AI CLI tools. By default, it uses Claud
 
 The prompt content and `--dangerously-skip-permissions` (in containers) are added automatically at runtime.
 
+### Skills Configuration
+
+Skills are reusable instruction sets that extend Claude's behavior for specific languages or project requirements. They inject additional context and rules into prompts.
+
+Configure skills in `.ralph/config.json`:
+
+```json
+{
+  "claude": {
+    "skills": [
+      {
+        "name": "swift-main-naming",
+        "description": "Prevents naming files main.swift when using @main attribute",
+        "instructions": "IMPORTANT: In Swift, files with @main attribute MUST NOT be named main.swift...",
+        "userInvocable": false
+      }
+    ]
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | Unique skill identifier (kebab-case) |
+| `description` | Brief description shown during selection |
+| `instructions` | Full instructions injected into Claude's prompt |
+| `userInvocable` | If `true`, user can invoke via `/skill-name` (default: `true`) |
+
+During `ralph init`, you can select built-in skills for your chosen language. See [docs/SKILLS.md](docs/SKILLS.md) for detailed configuration, custom skills, and best practices.
+
 ### Stream-JSON Output
 
 Ralph supports stream-json output mode for real-time streaming of AI responses. This feature provides cleaner terminal output and enables recording of raw JSON logs for debugging or replay.

package/dist/config/cli-providers.json

@@ -122,17 +122,16 @@
       "command": "goose",
       "defaultArgs": [],
       "yoloArgs": [],
-      "promptArgs": ["run", "--text"],
+      "promptArgs": ["run", "--no-session", "--with-builtin", "developer", "--text"],
       "streamJsonArgs": ["--output-format", "stream-json"],
       "docker": {
-        "install": "# Install Goose CLI (requires Python)\nRUN apt-get update && apt-get install -y python3 python3-pip python3-venv && rm -rf /var/lib/apt/lists/* \\\n    && pip3 install --break-system-packages --no-cache-dir goose-ai",
+        "install": "# Install Goose CLI (as node user)\nRUN su - node -c 'curl -fsSL https://github.com/block/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash' \\\n    && echo 'export PATH=\"$HOME/.local/bin:$PATH\"' >> /home/node/.zshrc \\\n    && echo 'export GOOSE_MODE=auto' >> /home/node/.zshrc",
         "note": "Check 'goose --help' for available flags"
       },
       "envVars": ["OPENAI_API_KEY", "ANTHROPIC_API_KEY"],
       "credentialMount": null,
       "modelConfig": {
-        "envVar": "GOOSE_PROVIDER",
-        "note": "Set provider via GOOSE_PROVIDER env var"
+        "note": "Run 'goose configure' to setup the provider and model. See https://block.github.io/goose/docs/getting-started/providers/"
       },
       "modelArgs": ["--model"]
     },

package/dist/config/skills.json

@@ -1,5 +1,13 @@
 {
   "skills": {
+    "common": [
+      {
+        "name": "sandbox-safe",
+        "description": "Prevents starting dev servers in sandboxed environments",
+        "instructions": "IMPORTANT: You are running in a sandboxed Docker/Podman container. Do NOT start long-running development servers to verify your work.\n\nAVOID these commands for verification:\n- `npm run dev`, `npm start`, `yarn dev`\n- `uvicorn`, `gunicorn`, `flask run`, `python -m http.server`\n- `rails server`, `rails s`\n- `go run main.go` (for servers)\n- `cargo run` (for servers)\n- Any command that starts a web server and waits for connections\n\nWHY: Dev servers hang in sandboxed environments because:\n1. Network restrictions may block telemetry/update checks\n2. The server waits indefinitely for connections\n3. This prevents the iteration from completing\n\nINSTEAD, use these verification methods:\n- `npm run build` or `npx tsc --noEmit` (TypeScript/JavaScript)\n- `go build ./...` (Go)\n- `cargo build` or `cargo check` (Rust)\n- `python -m py_compile file.py` or `mypy .` (Python)\n- `bundle exec rake` or `rails runner \"puts 'OK'\"` (Ruby)\n- Run unit tests: `npm test`, `pytest`, `go test ./...`\n\nIf you need to verify a server starts correctly, use a brief timeout:\n```bash\ntimeout 5 npm run dev || true  # Only if absolutely necessary\n```\n\nBut prefer build/compile checks over actually starting servers.",
+        "userInvocable": false
+      }
+    ],
     "swift": [
       {
         "name": "swift-main-naming",

package/dist/templates/prompts.js

@@ -61,7 +61,9 @@ export function getSkillsJson() {
 }
 export function getSkillsForLanguage(language) {
     const skills = getSkillsJson().skills;
-    return skills[language] || [];
+    const languageSkills = skills[language] || [];
+    const commonSkills = skills["common"] || [];
+    return [...commonSkills, ...languageSkills];
 }
 export function getLanguages() {
     if (!_languagesCache) {

package/dist/utils/config.js

@@ -25,6 +25,10 @@ export function getCliConfig(config) {
         if (result.fileArgs === undefined && provider?.fileArgs !== undefined) {
             result.fileArgs = provider.fileArgs;
         }
+        // Use provider's yoloArgs if not already set
+        if (result.yoloArgs === undefined && provider?.yoloArgs !== undefined) {
+            result.yoloArgs = provider.yoloArgs;
+        }
         // Default promptArgs for backwards compatibility
         if (result.promptArgs === undefined) {
             result.promptArgs = ["-p"];

package/docs/PRD-GENERATOR.md

@@ -360,3 +360,63 @@ After generating prd.json, verify:
 | Missing verification | No way to confirm completion | Add test/build/check step |
 | Too many steps | Overwhelming, hard to track | Max 4-5 steps per item |
 | Wrong granularity | Items too big or too small | One iteration = one item |
+| Starting dev servers | Hangs in sandbox, blocks iteration | Use build/typecheck instead |
+
+## Sandbox Constraints
+
+When running in Docker/Podman sandboxes, certain operations can cause the iteration to hang or fail. Write PRD steps that avoid these issues.
+
+### Avoid Starting Dev Servers
+
+**Problem:** Starting development servers (`npm run dev`, `uvicorn --reload`, `rails server`, etc.) in verification steps can hang the sandbox:
+- Servers wait for network connections that may be blocked by firewall
+- Long-running processes prevent the iteration from completing
+- Telemetry/update checks may timeout on restricted networks
+
+**Bad:**
+```json
+"steps": [
+  "Create the component",
+  "Run `npm run dev` and verify server starts on port 3000",
+  "Open browser and check the page renders"
+]
+```
+
+**Good:**
+```json
+"steps": [
+  "Create the component",
+  "Run `npm run build` and verify compilation succeeds",
+  "Run `npm run lint` to check for errors"
+]
+```
+
+### Verification Alternatives
+
+Instead of starting servers, use these verification methods:
+
+| Instead of | Use |
+|------------|-----|
+| `npm run dev` | `npm run build` or `npx tsc --noEmit` |
+| `uvicorn app:app` | `python -m py_compile app.py` or `mypy app.py` |
+| `rails server` | `rails runner "puts 'OK'"` or `bundle exec rake` |
+| `go run main.go` | `go build ./...` |
+| curl to localhost | Unit tests or integration tests |
+
+### Network-Dependent Operations
+
+Be aware that sandboxed environments may have restricted network access:
+- Package installs work (npm, pip, etc.) if registries are allowed
+- External API calls may be blocked
+- Telemetry and update checks may timeout
+
+**Tip:** Add domains your app needs to the firewall allowlist in `.ralph/config.json`:
+```json
+{
+  "docker": {
+    "firewall": {
+      "allowedDomains": ["api.example.com", "cdn.example.com"]
+    }
+  }
+}
+```

package/docs/SKILLS.md

@@ -0,0 +1,203 @@
+# Skills Configuration
+
+Skills are reusable instruction sets that extend Claude's behavior for specific languages, frameworks, or project requirements. They inject additional context and rules into the prompt sent to Claude during each iteration.
+
+## Overview
+
+Skills help enforce best practices, prevent common mistakes, and provide domain-specific guidance. For example, a Swift skill might prevent naming files `main.swift` when using the `@main` attribute.
+
+## Configuration
+
+Skills are configured in `.ralph/config.json` under the `claude.skills` array:
+
+```json
+{
+  "claude": {
+    "skills": [
+      {
+        "name": "skill-name",
+        "description": "Brief description of what the skill does",
+        "instructions": "Detailed instructions injected into Claude's prompt",
+        "userInvocable": false
+      }
+    ]
+  }
+}
+```
+
+## Skill Definition
+
+Each skill has the following fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Unique identifier for the skill. Use kebab-case (e.g., `swift-main-naming`). |
+| `description` | string | Yes | Brief human-readable description shown during selection. |
+| `instructions` | string | Yes | Full instructions injected into Claude's prompt. Can include examples, rules, and formatting. |
+| `userInvocable` | boolean | No | If `true`, user can invoke the skill via `/skill-name`. Defaults to `true`. |
+
+### Field Details
+
+#### name
+
+The skill name should be:
+- Unique within the project
+- Descriptive of its purpose
+- Use kebab-case (lowercase with hyphens)
+
+Examples: `swift-main-naming`, `react-hooks-rules`, `go-error-handling`
+
+#### description
+
+A concise one-line description that:
+- Explains what the skill does
+- Helps users understand when to use it
+- Is shown during `ralph init` skill selection
+
+#### instructions
+
+The detailed instructions that Claude receives. Best practices:
+- Start with a clear statement of the rule or guidance
+- Explain the "why" so Claude understands the reasoning
+- Include concrete examples of correct and incorrect patterns
+- Use code blocks for examples
+- Keep instructions focused on a single concern
+
+Example:
+```
+IMPORTANT: In Swift, files containing the @main attribute MUST NOT be named main.swift.
+
+When the @main attribute is used, 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.
+
+RULES:
+- Never name a file main.swift if it contains @main attribute
+- Use descriptive names like App.swift or the actual type name
+
+BAD:
+// main.swift
+@main struct App { ... }
+
+GOOD:
+// App.swift
+@main struct App { ... }
+```
+
+#### userInvocable
+
+Controls whether the skill can be invoked on-demand:
+- `true` (default): User can trigger the skill with `/skill-name`
+- `false`: Skill is always active but cannot be explicitly invoked
+
+Set to `false` for skills that should always be active (like language-specific rules).
+
+## Built-in Skills
+
+Ralph includes built-in skills for specific languages in `src/config/skills.json`. During `ralph init`, you can select which skills to enable for your project.
+
+### Currently Available Skills
+
+**Common Skills** (applied to all languages):
+
+| Skill Name | Description |
+|------------|-------------|
+| `sandbox-safe` | Prevents starting dev servers in sandboxed environments |
+
+**Language-Specific Skills**:
+
+| Language | Skill Name | Description |
+|----------|------------|-------------|
+| Swift | `swift-main-naming` | Prevents naming files main.swift when using @main attribute |
+
+## Adding Skills During Init
+
+When running `ralph init`, you'll be prompted to select skills for your chosen language:
+
+```bash
+ralph init
+
+# ... language selection ...
+
+? Select skills for Swift (optional):
+  ◉ swift-main-naming - Prevents naming files main.swift when using @main attribute
+```
+
+Selected skills are automatically added to your `.ralph/config.json`.
+
+## Custom Skills
+
+You can add custom skills directly to your config file:
+
+```json
+{
+  "claude": {
+    "skills": [
+      {
+        "name": "project-conventions",
+        "description": "Project-specific coding conventions",
+        "instructions": "Follow these project conventions:\n\n1. Use camelCase for variables\n2. Use PascalCase for types\n3. All public functions must have documentation comments\n4. Error messages must include error codes in format ERR-XXX",
+        "userInvocable": false
+      },
+      {
+        "name": "review-checklist",
+        "description": "Code review checklist",
+        "instructions": "Before committing, verify:\n- [ ] All tests pass\n- [ ] No console.log statements\n- [ ] No TODO comments without issue links\n- [ ] Public APIs are documented",
+        "userInvocable": true
+      }
+    ]
+  }
+}
+```
+
+## Skill Scopes
+
+Skills can be scoped for different purposes:
+
+### Language-Specific Skills
+Target common pitfalls or best practices for a language:
+- Naming conventions
+- Common anti-patterns
+- Language-specific idioms
+
+### Framework Skills
+Target framework-specific patterns:
+- React hooks rules
+- Express middleware patterns
+- Django model conventions
+
+### Project Skills
+Target project-specific requirements:
+- Code style guides
+- Architecture decisions
+- Team conventions
+
+## How Skills Are Applied
+
+When ralph runs an iteration:
+
+1. Skills from `claude.skills` are loaded from config
+2. Skill instructions are injected into the prompt template
+3. Claude receives the combined prompt with all active skill instructions
+
+This ensures Claude consistently follows your defined rules across all iterations.
+
+## Troubleshooting
+
+### Skill not appearing in selection
+
+- Ensure the skill is defined in `src/config/skills.json` under the correct language key
+- Verify the JSON syntax is valid
+
+### Skill instructions not being followed
+
+- Check that the skill is listed in `.ralph/config.json` under `claude.skills`
+- Ensure the instructions are clear and specific
+- Add concrete examples of correct/incorrect patterns
+
+### Conflicting skills
+
+If two skills have conflicting instructions:
+- Review and consolidate the instructions
+- Remove the less important skill
+- Adjust instructions to handle edge cases explicitly

package/package.json

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