ralphflow 0.3.0 → 0.5.0

package/README.md

@@ -11,25 +11,29 @@ Define pipelines as loops, coordinate parallel agents via file-based trackers, a
 ## Quick Start
 
 ```bash
-# 1. Make sure you have a CLAUDE.md in your project
-#    (or let Claude create one: claude "Initialize CLAUDE.md for this project")
+# In your project with a CLAUDE.md
+npx ralphflow
+```
+
+This starts the web dashboard at `http://localhost:4242` and opens it in your browser. From the dashboard you can create apps, run loops, edit prompts, monitor agents, and browse archives — all in one place.
+
+### CLI Commands
 
-# 2. Initialize a flow
+```bash
+# Initialize a new flow
 npx ralphflow init --template code-implementation --name my-app
 
-# 3. Run the story loop — describe what you want to build
+# Run loops
 npx ralphflow run story
-
-# 4. Run the tasks loop — agents implement your stories
 npx ralphflow run tasks
-
-# 5. Run with multiple agents for parallel execution
-npx ralphflow run tasks --agents 3
-
-# 6. Deliver — review, get feedback, resolve
+npx ralphflow run tasks --multi-agent   # Multi-agent — one terminal per agent
 npx ralphflow run delivery
 
-# 7. Check progress anytime
+# Run with live dashboard alongside
+npx ralphflow run tasks --ui
+npx ralphflow e2e --ui
+
+# Check status
 npx ralphflow status
 ```
 
@@ -41,9 +45,9 @@ The default `code-implementation` template ships with three loops:
 
 | Loop | Purpose | Mode |
 |------|---------|------|
-| **Story Loop** | Break features into stories and tasks | Interactive — Claude asks you questions |
-| **Tasks Loop** | Implement tasks, commit code, update CLAUDE.md | Single or multi-agent (autonomous) |
-| **Delivery Loop** | Review completed work, gather feedback | Interactive — Claude presents deliverables |
+| **Story Loop** | Break features into stories and tasks | Interactive Claude Code session |
+| **Tasks Loop** | Implement tasks, commit code, update CLAUDE.md | Single or multi-agent (`--multi-agent`) |
+| **Delivery Loop** | Review completed work, gather feedback | Interactive Claude Code session |
 
 ### Pipeline Flow
 
@@ -58,9 +62,33 @@ Story Loop          Tasks Loop              Delivery Loop
                    agent-1 agent-2 agent-3
 ```
 
+## Web Dashboard
+
+The dashboard (`http://localhost:4242`) is the primary interface for managing workflows.
+
+**Features:**
+- **Live pipeline view** — color-coded loop status (complete/running/pending)
+- **Per-loop detail** — stage, active item, progress bar, agent table
+- **Prompt editor** — edit prompt files with Cmd+S save and dirty indicator
+- **Tracker viewer** — auto-updates as agents write via WebSocket
+- **Model selector** — per-loop model configuration (claude-sonnet-4-6, claude-opus-4-6, etc.)
+- **Attention notifications** — real-time alerts when Claude needs input, with desktop notifications and audio chime
+- **App archiving** — snapshot and reset flows to start fresh
+- **Archive browser** — browse past snapshots with timeline view and file viewer
+- **Template creator** — build custom templates with a visual config builder and live YAML preview
+- **Create app** — initialize new flows from built-in or custom templates
+
+```bash
+npx ralphflow dashboard              # Default port 4242
+npx ralphflow dashboard -p 3000      # Custom port
+npx ralphflow ui                     # Alias
+```
+
 ## Commands
 
-All commands are run via `npx ralphflow` — no global install needed.
+### `npx ralphflow` (no args)
+
+Starts the dashboard and opens it in your browser. This is the recommended way to use RalphFlow.
 
 ### `npx ralphflow init`
 
@@ -72,77 +100,93 @@ npx ralphflow init --template code-implementation --name api # Non-interactive
 npx ralphflow init --template research --name kashi          # Research pipeline
 ```
 
-Requires `CLAUDE.md` to exist in your project root. If it doesn't, you'll be prompted to create one first.
-
 **Options:**
-- `-t, --template <name>` — Template to use (`code-implementation`, `research`)
+- `-t, --template <name>` — Template to use (`code-implementation`, `research`, or any custom template)
 - `-n, --name <name>` — Custom name for the flow
 
 ### `npx ralphflow run <loop>`
 
-Runs a loop. Handles the iteration cycle — spawning Claude, detecting completion signals, and restarting on `kill -INT $PPID`.
+Runs a loop. Handles the iteration cycle — spawning Claude, detecting completion signals, and restarting.
 
 ```bash
-npx ralphflow run story                    # Run story loop
+npx ralphflow run story                    # Run story loop (interactive Claude session)
 npx ralphflow run tasks                    # Run tasks loop (single agent)
-npx ralphflow run tasks --agents 3         # Run with 3 parallel agents
-npx ralphflow run delivery                 # Run delivery loop
-npx ralphflow run story --flow my-app      # Specify which flow (when multiple exist)
-npx ralphflow run tasks --max-iterations 5 # Limit iterations
+npx ralphflow run tasks --multi-agent      # Run as a multi-agent instance
+npx ralphflow run tasks --ui              # Run with live dashboard alongside
+npx ralphflow run tasks -m claude-opus-4-6  # Use a specific model
 ```
 
+**Multi-agent mode:** Each terminal is one agent. Open multiple terminals, run `--multi-agent` in each, and they auto-assign sequential agent IDs (`agent-1`, `agent-2`, ...) via PID-based lock files.
+
 **Options:**
-- `-a, --agents <n>` — Number of parallel agents (default: 1)
-- `-m, --model <model>` — Claude model to use
+- `--multi-agent` — Run as a multi-agent instance
+- `--ui` — Start the web dashboard alongside execution
+- `-m, --model <model>` — Claude model to use (overrides per-loop config)
 - `-n, --max-iterations <n>` — Maximum iterations (default: 30)
-- `-f, --flow <name>` — Which flow to run (auto-detected if only one exists)
+- `-f, --flow <name>` — Which flow to run
 
-### `npx ralphflow status`
+### `npx ralphflow e2e`
 
-Shows the current state of all loops across all flows.
+Runs all loops end-to-end with SQLite orchestration. Skips loops already completed.
 
 ```bash
-npx ralphflow status                # All flows
-npx ralphflow status --flow my-app  # Specific flow
+npx ralphflow e2e                   # Run all loops
+npx ralphflow e2e --ui              # With live dashboard
 ```
 
+**Options:**
+- `--ui` — Start the web dashboard alongside
+- `-m, --model <model>` — Claude model to use
+- `-n, --max-iterations <n>` — Maximum iterations per loop (default: 30)
+- `-f, --flow <name>` — Which flow to run
+
+### `npx ralphflow status`
+
+Shows the current state of all loops.
+
 ```
   RalphFlow — my-app
 
-  Loop           Stage              Active  Progress
-  Story Loop     analyze            none    0/0
-  Tasks Loop     —                  none    3/6
-    agent-1      understand-execute TASK-4  2026-03-08T10:00
-    agent-2      verify-document    TASK-5  2026-03-08T10:01
-  Delivery Loop  idle               none    0/0
+  Loop           Stage    Active  Progress
+  Story Loop     analyze  none    0/0
+  Tasks Loop     —        none    3/6
+  Delivery Loop  idle     none    0/0
 ```
 
-**Options:**
-- `-f, --flow <name>` — Show status for a specific flow
-
-## Multiple Flows
-
-You can run multiple flows in the same project — useful for separate workstreams:
+## Per-Loop Model Configuration
 
-```bash
-npx ralphflow init --template code-implementation --name frontend
-npx ralphflow init --template code-implementation --name backend
-npx ralphflow init --template research --name market-research
+Each loop in `ralphflow.yaml` supports an optional `model` field:
 
-npx ralphflow status  # Shows all three
+```yaml
+loops:
+  story-loop:
+    model: claude-sonnet-4-6
+  tasks-loop:
+    model: claude-opus-4-6
 ```
 
-When multiple flows exist, use `--flow <name>` with `run` and `status`.
+**Resolution order:** CLI `--model` flag → per-loop `model` from config → Claude default. The dashboard includes a model selector dropdown to configure this per loop.
 
 ## Templates
 
-### `code-implementation`
+### Built-in
+
+- **`code-implementation`** — Story → Tasks → Delivery pipeline for code projects
+- **`research`** — Discovery → Research → Story → Document pipeline for research projects
 
-Story → Tasks → Delivery pipeline for code projects. Battle-tested across 28 stories and 84 tasks.
+### Custom Templates
 
-### `research`
+Create custom templates via the dashboard's Template Creator or the API. Custom templates are stored in `.ralph-flow/.templates/` and appear alongside built-in templates when creating new apps.
 
-Multi-loop research pipeline with discovery, research, story, evolution, issue, datapoints, and merge loops. Tested across 467 places and 94 roads in a Kashi/Varanasi research project.
+## Multiple Flows
+
+Run multiple flows in the same project for separate workstreams:
+
+```bash
+npx ralphflow init --template code-implementation --name frontend
+npx ralphflow init --template code-implementation --name backend
+npx ralphflow init --template research --name market-research
+```
 
 ## Project Structure
 
@@ -157,19 +201,14 @@ your-project/
         ├── 00-story-loop/
         │   ├── prompt.md                  # Agent instructions
         │   ├── tracker.md                 # State tracking
-        │   ├── stories.md                 # Story definitions
-        │   └── loop.md                    # Manual run instructions
+        │   └── stories.md                 # Story definitions
         ├── 01-tasks-loop/
         │   ├── prompt.md
         │   ├── tracker.md
-        │   ├── tasks.md
-        │   ├── loop.md
-        │   ├── phases/                    # Phase documentation
-        │   └── testing/                   # Test documentation
+        │   └── tasks.md
         └── 02-delivery-loop/
             ├── prompt.md
-            ├── tracker.md
-            └── loop.md
+            └── tracker.md
 ```
 
 ## CLAUDE.md
@@ -177,11 +216,10 @@ your-project/
 `CLAUDE.md` is a first-class citizen of the workflow:
 
 - **Story loop** reads it for project context
-- **Tasks loop** reads it for architecture, stack, conventions, commands, and URLs
-- **Tasks loop updates it** after each task (keeping changes under 150 words net)
+- **Tasks loop** reads it for architecture, stack, conventions, and commands — and updates it after each task
 - **Delivery loop** reads it for project context and patterns
 
-RalphFlow requires `CLAUDE.md` to exist before initializing a flow. Create one with your project description, tech stack, dev commands, and conventions — or let Claude generate it for you.
+RalphFlow requires `CLAUDE.md` to exist before initializing a flow.
 
 ## Install
 
@@ -191,14 +229,6 @@ No install required — use `npx ralphflow` directly. Or install globally:
 npm install -g ralphflow
 ```
 
-Then use without the `npx` prefix:
-
-```bash
-ralphflow init --template code-implementation --name my-app
-ralphflow run story
-ralphflow status
-```
-
 ## Requirements
 
 - Node.js >= 18