@neriros/ralphy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neriros
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,167 @@
+# Ralphy
+
+An iterative AI task execution framework. Ralphy orchestrates multi-phase autonomous work using Claude or Codex engines, with built-in state management, progress tracking, and cost safeguards.
+
+## How It Works
+
+Ralphy breaks down complex tasks into structured phases:
+
+```mermaid
+graph LR
+    R[Research] --> P[Plan] --> E[Exec] --> V[Review] --> D[Done]
+    V -->|issues found| E
+```
+
+Each phase runs in a loop — the engine iterates until the phase's completion criteria are met, then auto-advances to the next phase. A `STEERING.md` file lets you guide the agent mid-flight.
+
+## Installation
+
+### npm (global)
+
+```bash
+npm install -g ralphy
+# or
+bunx ralphy
+```
+
+Requires [Bun](https://bun.sh) as the runtime.
+
+### Local (per-project)
+
+```bash
+bun install
+make install            # Install to ./.ralph
+make install ~           # Install to ~/.ralph
+make install /path/to   # Install to /path/to/.ralph
+```
+
+This builds the CLI and MCP server, copies them to `.ralph/bin/`, sets up phase definitions and templates, configures `.mcp.json`, and adds a `ralph` script to `package.json`. The `.ralph/` directory is gitignored by default.
+
+### Prerequisites
+
+- [Bun](https://bun.sh)
+- [Claude CLI](https://docs.anthropic.com/en/docs/claude-cli) (for the Claude engine)
+- `jq` (for installation)
+
+## Usage
+
+### Create and Run a Task
+
+```bash
+ralph task --name fix-auth --prompt "Fix the JWT validation bug" --claude opus --max-iterations 10
+```
+
+The engine defaults to Claude Opus.
+
+### Interactive Mode
+
+```bash
+ralph task --name fix-auth --prompt "Fix the JWT validation bug" --interactive
+```
+
+Runs the research and plan phases interactively (with direct terminal I/O), then switches to automated execution for the remaining phases. Useful when you want to guide early discovery and let the agent execute autonomously.
+
+### Resume a Task
+
+```bash
+ralph task --name fix-auth
+```
+
+If the task already exists, it resumes from where it left off.
+
+### Check Status
+
+```bash
+ralph list                    # Table of all tasks
+ralph status --name fix-auth  # Detailed view of one task
+```
+
+### Manual Phase Control
+
+```bash
+ralph advance --name fix-auth              # Advance to next phase
+ralph set-phase --name fix-auth --phase exec  # Jump to a specific phase
+```
+
+## CLI Options
+
+| Option                 | Description                                              |
+| ---------------------- | -------------------------------------------------------- |
+| `--name <name>`        | Task name (required for most commands)                   |
+| `--prompt <text>`      | Task description                                         |
+| `--prompt-file <path>` | Read prompt from a file                                  |
+| `--claude [model]`     | Use Claude engine (haiku/sonnet/opus)                    |
+| `--codex`              | Use Codex engine                                         |
+| `--model <model>`      | Set model (haiku/sonnet/opus)                            |
+| `--no-execute`         | Stop after research + plan phases                        |
+| `--interactive`        | Run research + plan interactively, then automate         |
+| `--max-iterations <N>` | Stop after N iterations (0 = unlimited)                  |
+| `--max-cost <N>`       | Stop when cost exceeds $N                                |
+| `--max-runtime <N>`    | Stop after N minutes                                     |
+| `--max-failures <N>`   | Stop after N consecutive identical failures (default: 5) |
+| `--unlimited`          | Set max iterations to 0 (unlimited, default)             |
+| `--delay <N>`          | Seconds to wait between iterations                       |
+| `--log`                | Log raw JSON stream output                               |
+| `--verbose`            | Verbose output                                           |
+
+## Phases
+
+| Phase        | Purpose                                      | Output                   |
+| ------------ | -------------------------------------------- | ------------------------ |
+| **Research** | Study the codebase and gather context        | `RESEARCH.md`            |
+| **Plan**     | Design the implementation approach           | `PLAN.md`, `PROGRESS.md` |
+| **Exec**     | Implement items from the progress checklist  | Code changes             |
+| **Review**   | Verify the work, loop back to exec if needed | Updated `PROGRESS.md`    |
+| **Done**     | Terminal phase — task is complete            | —                        |
+
+## Task Files
+
+Each task lives in `.ralph/tasks/<name>/` and contains:
+
+| File             | Purpose                                          |
+| ---------------- | ------------------------------------------------ |
+| `state.json`     | Task state, usage stats, and history             |
+| `STEERING.md`    | Your guidance to the agent (editable anytime)    |
+| `RESEARCH.md`    | Agent's research findings                        |
+| `PLAN.md`        | Agent's implementation plan                      |
+| `PROGRESS.md`    | Checklist tracking execution progress            |
+| `INTERACTIVE.md` | Context saved from interactive session (if used) |
+| `STOP`           | Create this file to signal the loop to stop      |
+
+## MCP Server
+
+Ralphy includes an MCP server that exposes task management tools to Claude agents. It's automatically configured during installation. Available tools:
+
+- `ralph_list_tasks` — List tasks with status and progress
+- `ralph_get_task` — Get task details
+- `ralph_create_task` / `ralph_run_task` — Create and run tasks
+- `ralph_read_document` — Read task documents
+- `ralph_advance_phase` — Advance or set phase
+- `ralph_update_steering` — Update STEERING.md
+- `ralph_finish_interactive` — Complete interactive session and hand off to automated phases
+- `ralph_list_checklists` / `ralph_apply_checklist` — Manage verification checklists
+
+## Project Structure
+
+```
+ralphy/
+├── apps/
+│   ├── cli/          # CLI application
+│   └── mcp/          # MCP server
+├── packages/
+│   ├── core/         # State management, loop, progress
+│   ├── context/      # Storage abstraction
+│   ├── engine/       # Claude/Codex engine spawning
+│   ├── output/       # Terminal formatting
+│   ├── phases/       # Phase definitions and checklists
+│   └── types/        # Zod schemas and types
+└── Makefile
+```
+
+## Development
+
+```bash
+bun install
+bunx nx run-many -t lint,typecheck,test,build   # Run checks
+bunx nx run cli:build                            # Build CLI only
+```

package/dist/checklists/deploy.md

@@ -0,0 +1,5 @@
+# Deploy
+
+- [ ] **Check deployment status** — use Vercel MCP or CI dashboard to confirm the deploy succeeded.
+- [ ] **Read build logs on failure** — identify the error, fix locally, re-run static + test checklists, commit, push again.
+- [ ] **Smoke test the deployed URL** — verify the deployed version loads and the affected feature works.

package/dist/checklists/static.md

@@ -0,0 +1,6 @@
+# Static Analysis
+
+- [ ] **Lint** — run the project linter (see `CLAUDE.md` for command). Zero errors, zero warnings.
+- [ ] **Typecheck** — run the type checker. Zero errors.
+- [ ] **Build** — run a production build to catch anything lint/typecheck miss (import resolution, SSR issues, etc.).
+- [ ] **Format** — run the formatter. Zero errors.

package/dist/checklists/tests.md

@@ -0,0 +1,5 @@
+# Tests
+
+- [ ] **Unit tests** — run tests for affected libraries/modules. If tests don't exist for new code, create them.
+- [ ] **Integration tests** _(if applicable)_ — run if your changes touch API routes, database queries, or cross-module boundaries.
+- [ ] **E2E tests** _(if applicable)_ — run if your changes affect user-facing flows (see `CLAUDE.md` for e2e command).