ralphie 1.1.2 → 1.2.1

package/README.md

@@ -8,12 +8,12 @@
 
 # Ralphie
 
-**Let AI code while you sleep.**
+**Autonomous AI coding loops.**
 
-Ralphie runs AI in a loop until your project is done. Based on the [Ralph Wiggum technique](https://github.com/ghuntley/how-to-ralph-wiggum): describe what you want → AI builds it task by task → each task gets committed → come back to working code.
+Based on the [Ralph Wiggum technique](https://github.com/ghuntley/how-to-ralph-wiggum): describe what you want → AI builds it task by task → each task gets committed → come back to working code.
 
 ```bash
-/ralphie-spec "Todo app with auth"   # AI interviews you, creates spec
+ralphie spec "Todo app with auth"    # Creates spec
 ralphie run --all                    # Builds until done
 ```
 
@@ -38,26 +38,19 @@ npm install -g @openai/codex && export OPENAI_API_KEY=sk-...
 npm install -g opencode-ai && opencode auth login
 ```
 
-**3. Install Ralphie skills** via [add-skill](https://github.com/vercel-labs/add-skill)
+**3. Build something**
 
 ```bash
-npx add-skill skylarbarrera/ralphie
-```
-
-**4. Build something**
-
-```bash
-# Option A: Interactive (user present) - run in Claude/Codex/OpenCode:
-/ralphie-spec "REST API with JWT auth"
-
-# Option B: Autonomous (unattended) - run from CLI:
+# Create a spec
 ralphie spec "REST API with JWT auth"
 
-# Then run the loop:
-ralphie run --all                            # Builds it
-git log --oneline                            # See what was built
+# Run the loop
+ralphie run --all
+git log --oneline                        # See what was built
 ```
 
+**What happens next?** Ralphie generates a structured spec with research and analysis, then executes task-by-task with fresh context each iteration. Progress lives in git commits—the AI can fail, the loop restarts clean.
+
 ## How It Works
 
 Each iteration:
@@ -68,40 +61,51 @@ Each iteration:
 
 **The insight:** Progress lives in git, not the LLM's context. The AI can fail—next iteration starts fresh and sees only committed work.
 
-## Commands
+**What makes Ralphie different:** Structured specs with task IDs, status tracking, size budgeting, and verify commands. The AI knows exactly what to build, how to check it worked, and when it's done. No ambiguity, no drift.
+
+## Key Features
+
+**Compound Engineering** - Each failure makes the system better:
+- **Research phase**: Fetches framework-specific best practices from [skills.sh](https://skills.sh) (React, Next.js, Expo, etc.) and web research
+- **Dynamic tool selection**: Discovers best-in-class libraries for your stack (not hardcoded recommendations)
+- **Multi-agent review**: Security, performance, architecture checks before implementation
+- **Learnings system**: Captures failure→fix transitions as reusable knowledge
+- **Quality enforcement**: >80% test coverage mandatory, typed interfaces required, security by default
+- **Debug logs**: Full audit trail in `.ralphie/logs/` viewable with `ralphie logs`
 
-### CLI Commands
+**Senior Engineer Output** - Code quality built-in:
+- Research recommends current best tools (Zod, bcrypt, expo-auth-session)
+- Specs include explicit quality requirements (tests, security, architecture)
+- Test validator blocks task completion without >80% coverage
+- Clean, maintainable code with proper separation of concerns
+- See [Code Quality Standards](docs/code-quality-standards.md) for details
+
+Inspired by [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin). See [Architecture docs](docs/architecture.md) for details.
+
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `ralphie spec "desc"` | Generate spec autonomously (no user interaction) |
+| `ralphie spec "desc"` | Generate spec autonomously with research + analysis |
+| `ralphie spec --skip-research` | Skip deep research phase |
+| `ralphie spec --skip-analyze` | Skip SpecFlow analysis phase |
 | `ralphie run` | Run one iteration |
 | `ralphie run -n 5` | Run 5 iterations |
 | `ralphie run --all` | Run until spec complete |
+| `ralphie run --review` | Run multi-agent review before iteration |
+| `ralphie run --force` | Override P1 blocking (use with `--review`) |
 | `ralphie run --greedy` | Multiple tasks per iteration |
 | `ralphie run --headless` | JSON output for CI/CD |
 | `ralphie init` | Add to existing project |
 | `ralphie validate` | Check spec format |
 | `ralphie status` | Show progress of active spec |
 | `ralphie spec-list` | List active and completed specs |
+| `ralphie logs` | View iteration logs (with --tail, --filter) |
 | `ralphie archive` | Move completed spec to archive |
 
-Use `--harness codex` or `--harness opencode` to switch AI providers. See [CLI Reference](docs/cli.md) for all options.
-
-### Skills (via [add-skill](https://github.com/vercel-labs/add-skill))
-
-| Skill | Description |
-|-------|-------------|
-| `/ralphie-spec` | Generate spec through user interview (requires user) |
-| `/review-spec` | Validate spec format and content |
-| `/ralphie-iterate` | Execute one iteration (used by `ralphie run`) |
-| `/verify` | Pre-commit verification |
-
-Install all skills: `npx add-skill skylarbarrera/ralphie`
-
 ## Spec Format
 
-Ralphie works from structured specs in `specs/active/`:
+Ralphie works from structured specs in `.ralphie/specs/active/`:
 
 ```markdown
 # My Project
@@ -136,6 +140,15 @@ Goal: Build a REST API with authentication
 
 Tasks transition from `pending` → `in_progress` → `passed`/`failed`. See [Spec Guide](docs/spec-guide.md) for best practices.
 
+## Project Structure
+
+After `ralphie init`, you'll have:
+- `.ralphie/specs/active/` - Generated specs with task tracking
+- `.ralphie/logs/` - Timestamped logs (research, spec generation, iterations)
+- `.ralphie/learnings/` - Captured failure→fix knowledge
+- `.ralphie/state.txt` - Iteration progress log
+
+See [Architecture docs](docs/architecture.md) for complete structure and file formats.
 
 ## Troubleshooting
 
@@ -146,15 +159,15 @@ Tasks transition from `pending` → `in_progress` → `passed`/`failed`. See [Sp
 | `Missing ANTHROPIC_API_KEY` | `export ANTHROPIC_API_KEY=sk-ant-...` (add to .zshrc) |
 | `Missing OPENAI_API_KEY` | `export OPENAI_API_KEY=sk-...` (add to .zshrc) |
 | Stuck on same task | Check task status. Run `ralphie validate` |
-| No spec found | `/ralphie-spec` (with user) or `ralphie spec` (autonomous) |
+| No spec found | `ralphie spec "description"` to create one |
 
 ## Documentation
 
-- [CLI Reference](docs/cli.md) — All commands and options
-- [Spec Guide](docs/spec-guide.md) — Writing effective specs
-- [Skills](skills/SKILLS.md) — Installing and using Ralphie skills
-- [Architecture](docs/architecture.md) — How the loop works
-- [Harnesses](docs/harnesses.md) — Multi-AI provider support
+- [CLI Reference](docs/cli.md) - All commands, flags, harness options
+- [Spec Guide](docs/spec-guide.md) - Writing effective specs
+- [Architecture](docs/architecture.md) - How the loop works, compound engineering details
+- [Code Quality Standards](docs/code-quality-standards.md) - Senior engineer code quality expectations
+- [Comparison](docs/comparison.md) - How Ralphie compares to other tools
 
 ## Requirements