ralpi/README.md

# Ralpi

Execute tasks from task files until done using DAG-based dependency resolution with persistent progress tracking.

```bash
pi install npm:@mikefreno/ralpi
```

## Features

- **Parallel batching**: Independent tasks in each batch can run concurrently
- **Persistent progress**: Execution state saved to `.ralpi/progress.json`
- **Reflection system**: Each task produces a reflection for downstream tasks
- **Retry with backoff**: Failed tasks retry with exponential backoff
- **Multiple formats**: Supports simple checkboxes, and YAML
- **Tool usage tracking**: Detects and reports tool usage (read, write, edit, bash) from task execution
- **Configurable timeouts**: Task-level timeouts via meta blocks, with global fallback
- **Session saving**: Saves full task output for expandable session review
- **Resume auto-discovery**: Automatically finds and resumes interrupted execution

## Usage

```
/ralpi [task-file]  # Execute all tasks
/ralpi plan         # Alias to /task-manager to plan new tasks
/ralpi resume       # Resume paused execution
/ralpi reset        # Reset progress and .ralpi directory - does not modify PRD
```

### Highly recommended to use the task-manager prompt for prd construction, it's output pairs perfectly - /task-manager or /ralpi plan

## Tasks

### Simple Checkbox Format

```markdown
- [ ] 01: Setup project structure
- [ ] 02: Implement auth
- [ ] 03: Build API
```

### YAML Format

```yaml
objective: Build a web application
tasks:
  - id: "01"
    title: Setup project structure
    file: tasks/01-setup.md
    dependencies: []
  - id: "02"
    title: Implement auth
    file: tasks/02-auth.md
    depends_on: ["01"]
```

## Task IDs

Task IDs are zero-padded 2-digit strings (`01`, `02`, ...) with an optional
single lowercase letter suffix for sub-tasks inserted between two numbered
steps (e.g. `02b`, `02c`). The parser normalizes `2b` → `02b`.

```
- [ ] 01 — Setup
- [ ] 02 — Fix bugs
- [ ] 02b — Sub-step of 02 (inserted after the fact)
- [ ] 02c — Another sub-step of 02
- [ ] 03 — Continue
```

Use lettered sub-tasks when you discover mid-stream that a step needs to be
split. They let you preserve sibling numbering (`01`, `02`, `03`, ...) while
adding granularity between two existing steps.

## Dependencies

### Arrow Notation (recommended)

1 -> 2,3,4
5 -> 6
This means: "Task 1 must complete before tasks 2, 3, and 4 can start."

### Natural Language

13 depends on 17, 18, 19, 20
14 depends on 13, 15, 16

This means: "Task 13 depends on tasks 17, 18, 19, and 20."

### Parallel Groups (informational only)

1, 2, 3, 4 can be done in parallel
5, 6, 7, 8 can be done in parallel

Note: These lines are ignored by the parser. Use explicit dependencies to control execution order.

## Configuration

### Task-Level Timeout

You can set a timeout for individual tasks using a meta block in the task file:

```markdown
- [ ] 01: Setup project structure
  timeout: 10m
```

Supported formats: `10m` (minutes), `600s` (seconds), `3600000` (milliseconds)

### Config files

| Scope | Path |
|-------|------|
| **Global** | `~/.pi/ralpi/config.yaml` |
| **Project** | `./.ralpi/config.yaml` |

```yaml
execution:
  maxParallel: 3          # ralpi-level concurrency only
  models:                 # round-robin in <provider>/<model> format
    - google/gemini-3.5-flash # 1st and 3rd task in parallel
    - openai/gpt-5.5 # 2nd task in parallel
  autoCommit: true        # spawn a commit agent after each task completes
  autoReview: false        # spawn a review agent to review each commit
  implModel: ""           # model for task impl (sequential mode, empty = inherit parent)
  commitModel: ""         # model for commit sessions (empty = inherit task model)
  reviewModel: ""         # model for review sessions (empty = inherit task model)
  timeoutMs: 0            # per-task timeout in ms (0 = inherit Pi's defaults)
  commitTimeoutMs: 60000  # timeout for auto-commit agent sessions
  reviewTimeoutMs: 120000 # timeout for auto-review agent sessions
  loopTimeoutMs: 0        # max total loop duration in ms (0 = no limit)
prompts:
  projectContext: "Additional context for all tasks"
```

> `execution.models` uses slot-aware round-robin: with 3 models and 2 concurrent
> tasks, only the first two models are used. The third model is only touched when
> a third concurrent task starts. Freed model slots are reused before new ones
> are allocated.
> **Automatic failover**: if a provider/API is unreachable (rate limit, 503, etc.),
> the task automatically cycles to the next model in the list without counting it
> as a task failure. Each model is tried once before the task is marked as failed.
> **NOTE**: this is only used in parallel execution, in sequential mode the
> parent pi session's model is used

#### Auto-commit and Auto-review

When `autoCommit` is enabled (default), a follow-up agent session is spawned
after each task to stage and commit uncommitted changes. When `autoReview` is
enabled, a second follow-up session reviews the latest commit against the task
description. Both options can be overridden at loop startup via a selection
prompt.

`commitModel` and `reviewModel` accept `<provider>/<model>` strings (e.g.
`anthropic/claude-sonnet-4`) resolved via the model registry. When empty, the
task's model is inherited. `implModel` sets the model for task implementation
in sequential mode (overridden by `execution.models` round-robin in parallel
mode).

## State Files

- `.ralpi/progress.json` - Execution progress
- `.ralpi/reflections/` - Per-task reflections
- `.ralpi/prompts/` - Generated prompts
- `.ralpi/sessions/` - Full task output for review