computerlovetech · kasperjunge · Apr 2, 2026 · Apr 2, 2026
diff --git a/.gitignore b/.gitignore
@@ -11,6 +11,6 @@ ralph_logs/
 node_modules/
 .playwright-cli/
 mess/
-.ralphify/
+.agents/
 .DS_Store
 .coverage
diff --git a/AGENTS.md b/AGENTS.md
@@ -21,7 +21,7 @@ uv run mkdocs serve        # Preview docs at http://127.0.0.1:8000
 All source code is in `src/ralphify/`. The main file is `cli.py` — it contains the CLI commands and delegates to the engine for the core loop.
 
 Key modules:
-- `cli.py` — CLI commands (`run`, `new`, `init`); delegates to `_console_emitter.py` for terminal event rendering
+- `cli.py` — CLI commands (`run`, `scaffold`); delegates to `_console_emitter.py` for terminal event rendering
 - `engine.py` — Core run loop orchestration with structured event emission
 - `manager.py` — Multi-run orchestration (concurrent runs via threads)
 - `_frontmatter.py` — YAML frontmatter parsing (uses PyYAML) and the `RALPH_MARKER` constant
@@ -33,15 +33,12 @@ Key modules:
 - `_console_emitter.py` — Rich terminal rendering of events
 - `_output.py` — `ProcessResult` base class, combine stdout+stderr, format durations
 - `_brand.py` — Brand color constants shared across CLI and console rendering
-- `_source.py` — GitHub source parsing and git-based ralph fetching for `ralph add`
-- `_skills.py` — Skill installation, agent detection, and command building for `ralph new`
-- `skills/new-ralph/SKILL.md` — AI-guided ralph creation skill (bundled, installed into agent skill dir)
 
 Tests are in `tests/` with one file per module. Docs are in `docs/` using MkDocs with Material theme.
 
 ## Core concepts
 
-A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-level config, no `.ralphify/` directory, no `ralph init`.
+A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-level config, no special directories.
 
 **RALPH.md** has YAML frontmatter + a prompt body:
 - `agent` (required) — the agent command to run
@@ -60,14 +57,12 @@ A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-l
   - `docs/` (MkDocs) — user-facing docs: CLI reference, quick reference, writing prompts guide, cookbook. Only include what's relevant for users.
   - `docs/contributing/` — contributor/agent docs: codebase map, architecture. Only include what's relevant for contributors and coding agents.
   - `README.md` — keep short and high-level. Update only when the change affects the quickstart, install, or core concepts.
-  - `src/ralphify/skills/new-ralph/SKILL.md` — the skill that powers `ralph new`. Update when new frontmatter fields or features are added.
   - `CHANGELOG.md` — add an entry for every release.
 
 ## Boundaries
 
 ### Always Do
 - Run `uv run pytest` and `uv run ruff check .` before committing
-- Save all skills in `skills/` directory (not `.claude/skills/` which is gitignored)
 
 ## Traps
 

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -21,7 +21,7 @@ uv run mkdocs serve        # Preview docs at http://127.0.0.1:8000
 All source code is in `src/ralphify/`. The main file is `cli.py` — it contains the CLI commands and delegates to the engine for the core loop.
 
 Key modules:
-- `cli.py` — CLI commands (`run`, `new`, `init`); delegates to `_console_emitter.py` for terminal event rendering
+- `cli.py` — CLI commands (`run`, `scaffold`); delegates to `_console_emitter.py` for terminal event rendering
 - `engine.py` — Core run loop orchestration with structured event emission
 - `manager.py` — Multi-run orchestration (concurrent runs via threads)
 - `_frontmatter.py` — YAML frontmatter parsing (uses PyYAML) and the `RALPH_MARKER` constant
@@ -33,15 +33,12 @@ Key modules:
 - `_console_emitter.py` — Rich terminal rendering of events
 - `_output.py` — `ProcessResult` base class, combine stdout+stderr, format durations
 - `_brand.py` — Brand color constants shared across CLI and console rendering
-- `_source.py` — GitHub source parsing and git-based ralph fetching for `ralph add`
-- `_skills.py` — Skill installation, agent detection, and command building for `ralph new`
-- `skills/new-ralph/SKILL.md` — AI-guided ralph creation skill (bundled, installed into agent skill dir)
 
 Tests are in `tests/` with one file per module. Docs are in `docs/` using MkDocs with Material theme.
 
 ## Core concepts
 
-A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-level config, no `.ralphify/` directory, no `ralph init`.
+A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-level config, no special directories.
 
 **RALPH.md** has YAML frontmatter + a prompt body:
 - `agent` (required) — the agent command to run
@@ -60,14 +57,12 @@ A **ralph** is a directory containing a `RALPH.md` file. That's it. No project-l
   - `docs/` (MkDocs) — user-facing docs: CLI reference, quick reference, writing prompts guide, cookbook. Only include what's relevant for users.
   - `docs/contributing/` — contributor/agent docs: codebase map, architecture. Only include what's relevant for contributors and coding agents.
   - `README.md` — keep short and high-level. Update only when the change affects the quickstart, install, or core concepts.
-  - `src/ralphify/skills/new-ralph/SKILL.md` — the skill that powers `ralph new`. Update when new frontmatter fields or features are added.
   - `CHANGELOG.md` — add an entry for every release.
 
 ## Boundaries
 
 ### Always Do
 - Run `uv run pytest` and `uv run ruff check .` before committing
-- Save all skills in `skills/` directory (not `.claude/skills/` which is gitignored)
 
 ## Traps
 

diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ Any of these gives you the `ralph` command.
 A ralph is a directory with a `RALPH.md` file. Scaffold one:
 
 ```bash
-ralph init my-ralph
+ralph scaffold my-ralph
 ```
 
 Then edit `my-ralph/RALPH.md`:
@@ -140,22 +140,16 @@ my-ralph/
 
 **No project-level configuration.** No `ralph.toml`. No config files. A ralph is fully self-contained.
 
-## AI-guided setup
-
-```bash
-ralph new my-task
-```
-
-Launches an interactive agent conversation to scaffold a new ralph with the right commands and prompt for your project.
-
 ## Install ralphs from GitHub
 
+Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs:
+
 ```bash
-ralph add owner/repo              # Install all ralphs from a repo
-ralph add owner/repo/my-ralph     # Install a specific ralph by name
+agr add owner/repo/my-ralph      # Install a ralph from GitHub
+ralph run my-ralph                # Run it by name
 ```
 
-Installs ralphs to `.ralphify/ralphs/` so you can run them by name with `ralph run`.
+Ralphs installed by agr go to `.agents/ralphs/` and are automatically discovered by `ralph run`.
 
 ## Documentation
 

diff --git a/docs/agents.md b/docs/agents.md
@@ -15,12 +15,12 @@ This page shows how to configure the [`agent` frontmatter field](quick-reference
 
 ## Agent comparison
 
-| Agent | Stdin support | Streaming | `ralph new` support | Wrapper needed |
-|---|---|---|---|---|
-| [Claude Code](#claude-code) | Native (`-p`) | Yes — real-time activity tracking | Yes | No |
-| [Aider](#aider) | Via bash wrapper | No | No | Yes (`bash -c`) |
-| [Codex CLI](#codex-cli) | Native (`exec`) | No | Yes | No |
-| [Custom](#custom-wrapper-script) | You implement it | No | No | Yes (script) |
+| Agent | Stdin support | Streaming | Wrapper needed |
+|---|---|---|---|
+| [Claude Code](#claude-code) | Native (`-p`) | Yes — real-time activity tracking | No |
+| [Aider](#aider) | Via bash wrapper | No | Yes (`bash -c`) |
+| [Codex CLI](#codex-cli) | Native (`exec`) | No | No |
+| [Custom](#custom-wrapper-script) | You implement it | No | Yes (script) |
 
 If you're not sure which to pick: **start with Claude Code.** It has the deepest integration, the best autonomous coding capabilities, and is the default.
 

diff --git a/docs/blog/posts/the-ralph-standard.md b/docs/blog/posts/the-ralph-standard.md
@@ -150,14 +150,14 @@ ralph run ./ralphs/bug-hunter
 
 Declare `args: [focus]` and you get `--focus` on the CLI. The value fills `{{ args.focus }}` in the prompt. One ralph, many use cases.
 
-Because ralphs are just directories in a git repo, anyone can share them. If a repo contains a directory with a `RALPH.md`, you can install it with `ralph add`:
+Because ralphs are just directories in a git repo, anyone can share them. If a repo contains a directory with a `RALPH.md`, you can install it with [agr](https://github.com/computerlovetech/agr):
 
 ```bash
 # install a specific ralph from any GitHub repo
-ralph add owner/repo/ralph-name
+agr add owner/repo/ralph-name
 
 # install all ralphs in a repo
-ralph add owner/repo
+agr add owner/repo
 ```
 
 The [ralphify examples](https://github.com/computerlovetech/ralphify/tree/main/examples) are a good place to start — and the [cookbook](https://ralphify.co/docs/cookbook/) has more.

diff --git a/docs/cli.md b/docs/cli.md
@@ -1,13 +1,13 @@
 ---
 title: "CLI Reference: Run AI Coding Agents in Autonomous Loops"
-description: "Complete CLI reference for the ralph command — run autonomous AI coding loops, scaffold new agent prompts, install shared ralphs from GitHub, and configure RALPH.md frontmatter options."
-keywords: run AI agent in loop CLI, autonomous coding agent command line, ralph run command, ralph init, ralph add GitHub, RALPH.md frontmatter format, AI coding loop options, agent timeout iterations, user arguments CLI, ralphify CLI reference
+description: "Complete CLI reference for the ralph command — run autonomous AI coding loops, scaffold new agent prompts, and configure RALPH.md frontmatter options."
+keywords: run AI agent in loop CLI, autonomous coding agent command line, ralph run command, ralph scaffold, RALPH.md frontmatter format, AI coding loop options, agent timeout iterations, user arguments CLI, ralphify CLI reference
 ---
 
 # CLI Reference
 
 !!! tldr "TL;DR"
-    **`ralph run <path> -n 5`** runs the loop. **`ralph init <name>`** scaffolds a ralph from a template. **`ralph new`** creates one with AI guidance. **`ralph add owner/repo`** installs from GitHub. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter.
+    **`ralph run <path> -n 5`** runs the loop. **`ralph scaffold <name>`** creates a ralph from a template. Pass user args as `--name value` flags. Everything is configured in a single [`RALPH.md`](#ralphmd-format) file with YAML frontmatter.
 
 ## `ralph`
 
@@ -52,7 +52,7 @@ ralph run my-ralph --dir ./src             # Pass user args to the ralph
 
 | Argument / Option | Short | Default | Description |
 |---|---|---|---|
-| `PATH` | | (required) | Path to a ralph directory containing `RALPH.md`, a direct path to a `RALPH.md` file, or the name of an installed ralph (from `ralph add`) |
+| `PATH` | | (required) | Path to a ralph directory containing `RALPH.md`, a direct path to a `RALPH.md` file, or the name of an installed ralph in `.agents/ralphs/` |
 | `-n` | | unlimited | Max number of iterations |
 | `--stop-on-error` | `-s` | off | Stop loop if agent exits non-zero or times out |
 | `--delay` | `-d` | `0` | Seconds to wait between iterations |
@@ -116,13 +116,13 @@ The loop also stops automatically when:
 
 ---
 
-## `ralph init`
+## `ralph scaffold`
 
-Scaffold a new ralph with a ready-to-customize template. No AI agent required. For a guided setup, see [`ralph new`](#ralph-new) instead.
+Scaffold a new ralph with a ready-to-customize template.
 
 ```bash
-ralph init my-task      # Creates my-task/RALPH.md with a generic template
-ralph init              # Creates RALPH.md in the current directory
+ralph scaffold my-task      # Creates my-task/RALPH.md with a generic template
+ralph scaffold              # Creates RALPH.md in the current directory
 ```
 
 | Argument | Default | Description |
@@ -135,52 +135,6 @@ Errors if `RALPH.md` already exists at the target location.
 
 ---
 
-## `ralph new`
-
-Create a new ralph with AI-guided setup. Launches an interactive session where the agent guides you through creating a complete ralph via conversation.
-
-```bash
-ralph new              # Agent helps you choose a name and build everything
-ralph new my-task      # Start with a name already chosen
-```
-
-| Argument | Default | Description |
-|---|---|---|
-| `[NAME]` | none | Name for the new ralph. If omitted, the agent will help you choose |
-
-The command detects your [agent](agents.md) and installs a skill to guide the creation process.
-
----
-
-## `ralph add`
-
-Add a ralph from a GitHub repository. Installs it to `.ralphify/ralphs/<name>/` so you can run it by name.
-
-```bash
-ralph add owner/repo                                        # Install all ralphs in the repo
-ralph add owner/repo/ralph-name                             # Specific ralph by name
-ralph add https://github.com/owner/repo                     # Full GitHub URL
-ralph add https://github.com/owner/repo/tree/main/my-ralph  # URL copied from GitHub browser
-```
-
-| Argument | Default | Description |
-|---|---|---|
-| `SOURCE` | required | GitHub source — shorthand (`owner/repo`), subpath (`owner/repo/path`), or full GitHub URL |
-
-**How it resolves:**
-
-- `owner/repo` — if the repo root contains `RALPH.md`, installs it as a single ralph named after the repo. Otherwise, finds and installs all ralphs in the repo.
-- `owner/repo/ralph-name` — searches the repo for a directory named `ralph-name` containing `RALPH.md`. If multiple matches are found, prints the paths and asks you to use the full subpath to disambiguate.
-- `https://github.com/owner/repo/tree/branch/path` — extracts the path from the URL. This is the format you get when you copy a URL from the GitHub web UI while browsing a directory. The branch name is used only to locate the path — `ralph add` always clones the default branch.
-
-After adding, run the ralph by name:
-
-```bash
-ralph run ralph-name
-```
-
----
-
 ## RALPH.md format
 
 The `RALPH.md` file is the single configuration and prompt file for a ralph. It uses YAML frontmatter for settings and the body for the prompt text. See [Writing Prompts](writing-prompts.md) for detailed guidance on crafting effective prompts.

diff --git a/docs/contributing/codebase-map.md b/docs/contributing/codebase-map.md
@@ -19,22 +19,18 @@ The core loop is simple. The complexity lives in **prompt assembly** — running
 ```
 src/ralphify/           # All source code
 ├── __init__.py         # Version detection + app entry point
-├── cli.py              # CLI commands (run, new, init) — delegates to engine for the loop
+├── cli.py              # CLI commands (run, scaffold) — delegates to engine for the loop
 ├── engine.py           # Core run loop orchestration with structured event emission
 ├── manager.py          # Multi-run orchestration (concurrent runs via threads)
 ├── _resolver.py        # Template placeholder resolution ({{ commands.* }}, {{ args.* }}, {{ ralph.* }})
 ├── _agent.py           # Run agent subprocesses (streaming + blocking modes, log writing)
 ├── _run_types.py       # RunConfig, RunState, RunStatus, Command — shared data types
 ├── _runner.py          # Execute shell commands with timeout and capture output
 ├── _frontmatter.py     # Parse YAML frontmatter from RALPH.md, marker constants
-├── _source.py          # GitHub source parsing and git-based ralph fetching for `ralph add`
-├── _skills.py          # Skill installation and agent detection for `ralph new`
 ├── _console_emitter.py # Rich console renderer for run-loop events (ConsoleEmitter)
 ├── _events.py          # Event types, emitter protocol, and BoundEmitter convenience wrapper
 ├── _output.py          # ProcessResult base class, combine stdout+stderr, format durations
-├── _brand.py           # Brand color constants shared across CLI and console rendering
-└── skills/             # Bundled skill definitions (installed into agent skill dirs)
-    └── new-ralph/      # AI-guided ralph creation skill for `ralph new`
+└── _brand.py           # Brand color constants shared across CLI and console rendering
 
 tests/                  # Pytest tests — one test file per module
 docs/                   # MkDocs site (Material theme) — user-facing documentation
@@ -118,8 +114,6 @@ The CLI uses a `ConsoleEmitter` (defined in `_console_emitter.py`) that renders
 3. **`cli.py`** — All CLI commands. Validates frontmatter fields via extracted helpers (`_validate_agent`, `_validate_commands`, `_validate_credit`, `_validate_run_options`, `_validate_declared_args`), builds a `RunConfig`, and delegates to `engine.run_loop()` for the actual loop. Terminal event rendering lives in `_console_emitter.py`.
 4. **`_frontmatter.py`** — YAML frontmatter parsing. Extracts `agent`, `commands`, `args` from the RALPH.md file.
 5. **`_resolver.py`** — Template placeholder logic. Small file but critical.
-6. **`_skills.py`** + **`skills/`** — The skill system behind `ralph new`. `_skills.py` handles agent detection, reads bundled skill definitions from `skills/`, installs them into the agent's skill directory, and builds the command to launch the agent.
-
 ## Traps and gotchas
 
 ### If you change frontmatter fields...

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -7,7 +7,7 @@ keywords: set up autonomous AI coding agent, install ralphify, AI coding loop tu
 # Getting Started
 
 !!! tldr "TL;DR"
-    `uv tool install ralphify` → `ralph init my-ralph` → edit the RALPH.md → `ralph run my-ralph -n 1 --log-dir ralph_logs` to test → add a `commands` entry for your test suite → `ralph run my-ralph` to loop. The agent sees fresh test output each iteration and fixes what it breaks.
+    `uv tool install ralphify` → `ralph scaffold my-ralph` → edit the RALPH.md → `ralph run my-ralph -n 1 --log-dir ralph_logs` to test → add a `commands` entry for your test suite → `ralph run my-ralph` to loop. The agent sees fresh test output each iteration and fixes what it breaks.
 
 This tutorial walks through setting up ralphify, creating a ralph with commands, and running a productive autonomous loop. By the end, you'll have a self-healing coding loop that validates its own work.
 
@@ -41,10 +41,10 @@ ralphify 0.3.0
 
 ## Step 2: Create a ralph
 
-The fastest way to scaffold a ralph is `ralph init`:
+The fastest way to scaffold a ralph is `ralph scaffold`:
 
 ```bash
-ralph init my-ralph
+ralph scaffold my-ralph
 ```
 
 ```text
@@ -54,16 +54,16 @@ Edit the file, then run: ralph run my-ralph
 
 This creates `my-ralph/RALPH.md` with a ready-to-customize template including an example command, arg, and prompt. Edit the task section, [test it](#step-3-do-a-test-run), then follow [Step 4](#step-4-add-a-test-command) to add a test command — test feedback is what makes the loop self-healing.
 
-Alternatively, use `ralph new` for AI-guided setup, or create the file manually as shown below.
+Or create the file manually as shown below.
 
 !!! tip "Installing an existing ralph?"
-    If someone has shared a ralph on GitHub, skip the manual setup and install it directly:
+    Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub:
 
     ```bash
-    ralph add owner/repo
+    agr add owner/repo
     ```
 
-    This installs to `.ralphify/ralphs/` so you can run it by name with `ralph run <name>`. See the [CLI reference](cli.md#ralph-add) for all source formats.
+    This installs to `.agents/ralphs/` so you can run it by name with `ralph run <name>`.
 
 ### Manual setup
 

diff --git a/docs/index.md b/docs/index.md
@@ -127,16 +127,16 @@ Done: 3 iterations — 2 succeeded, 1 failed
 
 Edit `RALPH.md` while the loop is running — changes take effect on the next iteration.
 
-## Or grab one from GitHub
+## Or install one with agr
 
-Install a pre-built ralph from any GitHub repo and run it immediately:
+Install a pre-built ralph from any GitHub repo using [agr](https://github.com/computerlovetech/agr) and run it immediately:
 
 ```bash
-ralph add owner/repo/my-ralph    # Install a ralph from GitHub
+agr add owner/repo/my-ralph     # Install a ralph from GitHub
 ralph run my-ralph               # Run it
 ```
 
-`ralph add` fetches the ralph and installs it locally. You can install a single ralph by name, or all ralphs in a repo at once with `ralph add owner/repo`. See the [CLI reference](cli.md#ralph-add) for details.
+agr installs ralphs to `.agents/ralphs/` so you can run them by name.
 
 ---