Mike/ralpi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: updated docs to align with reality

Browse Source
This commit is contained in:
Michael Freno
2026-08-02 16:54:27 -04:00
parent f361f05f96
commit b0749467c9
3 changed files with 251 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

197
README.md
View File

@@ -8,35 +8,59 @@ 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`
- **DAG-based execution**: Tasks ordered via dependencies (arrow notation, natural language, "must be done before", or YAML)
- **Parallel batching**: Independent tasks in each batch run concurrently, round-robin across configured models
- **Persistent progress**: Execution state saved to `.ralpi/progress.json`, supporting multiple PRDs simultaneously
- **Resume & auto-resume**: `/ralpi-resume` continues paused execution; a session reload mid-loop auto-resumes via `.ralpi/loop-active.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
- **Phased plans**: `## Phase N — Title` sections add implicit phase-boundary dependencies
- **Model failover**: Unreachable providers cycle to the next model in the list before a task fails
- **Auto-commit / auto-review loop**: Optional per-task commit and review-gated re-execution until pass
- **Worktree isolation**: Parallel tasks run in separate git worktrees so they can't stomp each other, with batch-level merge-conflict resolution
- **Multiple formats**: Fio README (numbered + dependencies), phased, simple checkboxes, and YAML
- **Tool usage tracking**: Reports read/write/edit/bash usage from task execution
- **Configurable timeouts**: Task-level timeouts (inline, meta block, or YAML) with global fallback
## 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
/ralpi [task-file] # No args → show plan for README.md; path arg → run tasks
/ralpi-run [task-file] # Execute tasks from a task file
/ralpi-plan [prompt] # Open the Task Manager to plan tasks
/ralpi-resume [task-file] # Resume paused/interrupted execution
/ralpi-reset [task-file] # Reset execution progress — does not modify the PRD
```
### Highly recommended to use the task-manager prompt for prd construction, it's output pairs perfectly - /task-manager or /ralpi plan
`/ralpi` with no arguments shows the execution plan for the default task file. When the first token looks like a path (`@path`, `./path`, `path/file.md`, `.yaml`, etc.) it routes to `/ralpi-run`. Everything else is handled by the dedicated dash commands above (the old `/ralpi plan|resume|reset` subcommand syntax is gone).
> The task-manager prompt (`/ralpi-plan`) pairs perfectly with ralpi's task file formats — use it for PRD construction.
## Tasks
### Simple Checkbox Format
```markdown
- [ ] 01: Setup project structure
- [ ] 02: Implement auth
- [ ] 03: Build API
- [ ] Setup project structure
- [ ] Implement auth
- [ ] Build API
```
Checkbox-only files get sequential IDs (`01`, `02`, ...). Status characters: `[ ]` pending, `[x]` done, `[~]` in progress, `[!]` failed, `[-]` skipped.
### Fio Format (numbered tasks + dependencies)
```markdown
# Build a web application
## Tasks
- [ ] 01 — Setup project structure
- [ ] 02 — Implement auth
- [ ] 03 — Build API
## Dependencies
01 -> 02, 03
```
### YAML Format
@@ -72,40 +96,98 @@ 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.
## Phases
`## Phase N — Title` headings group tasks into phases and add an implicit
dependency from the first task of each phase to the last task of the
previous one, so phases always run in order:
```markdown
## Phase 1 — Push-to-Talk MVP
- [ ] 01 — Voice capture
- [ ] 02 — Transmission
## Phase 2 — Group Chat
- [ ] 03 — Channels
- [ ] 04 — Presence
```
## Dependencies
Dependency lines live in a `## Dependencies` section (or a plain
`Dependencies` heading). Multiple formats are supported and can be mixed.
### Arrow Notation (recommended)
```
1 -> 2,3,4
5 -> 6
This means: "Task 1 must complete before tasks 2, 3, and 4 can start."
```
"Task 1 must complete before tasks 2, 3, and 4 can start." Also supports
chains (`03 -> 04 -> 05`) and multi-prereq sources (`05, 07, 08 -> 13`).
### Natural Language
```
13 depends on 17, 18, 19, 20
14 depends on 13, 15, 16
22, 23, 24 depend on 21
```
This means: "Task 13 depends on tasks 17, 18, 19, and 20."
"Task 13 depends on tasks 17, 18, 19, and 20." `also depends on` is accepted.
### Parallel Groups (informational only)
### "must be done before"
1, 2, 3, 4 can be done in parallel
```
21 must be done before 22, 23, 24
02, 03 must be done before 04
```
### Parallel Groups
```
1, 2, 3, 4 can be done in parallel (Play Store prep)
5, 6, 7, 8 can be done in parallel
```
Note: These lines are ignored by the parser. Use explicit dependencies to control execution order.
Tasks listed in a parallel group are allowed to run concurrently. Group
declarations imply no cross-group dependencies, and intra-group
dependencies are still respected — group-aware batching produces a plan
where tasks from any group run as soon as their dependencies are
satisfied.
## Configuration
### Task-Level Timeout
You can set a timeout for individual tasks using a meta block in the task file:
Timeouts can be set inline on the task line, as an inline comment, via a
meta block in the Dependencies section, or in YAML:
```markdown
- [ ] 01: Setup project structure
timeout: 10m
- [ ] 01 — Setup project structure timeout: 10m
- [ ] 02 — Implement auth # timeout=30s
```
Supported formats: `10m` (minutes), `600s` (seconds), `3600000` (milliseconds)
```markdown
## Dependencies
01 -> 02
01 [timeout] = 10m
```
```yaml
tasks:
- id: "01"
title: Setup project structure
timeout: 15m
```
Supported units: `m` / `min` (minutes), `s` (seconds), `ms` (milliseconds).
Bare numbers default to minutes; in YAML, numeric values ≥ 1000 are treated
as milliseconds.
### Config files
@@ -114,23 +196,31 @@ Supported formats: `10m` (minutes), `600s` (seconds), `3600000` (milliseconds)
| **Global** | `~/.pi/ralpi/config.yaml` |
| **Project** | `./.ralpi/config.yaml` |
Project config overrides global, which overrides defaults. Keys set
explicitly in YAML skip the corresponding loop-startup prompt.
```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 # commit after each task (mandated when autoReview is on; standalone toggle when off)
autoReview: false # commit → review → loop on fail → merge on pass
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)
maxParallel: 3 # ralpi-level concurrency only (0 = unlimited)
models: # round-robin for parallel tasks, <provider>/<model>
- anthropic/claude-sonnet-4
- openai/gpt-4o
autoCommit: true # commit after each task (mandated when autoReview is on)
autoReview: false # commit → review → loop on fail → merge on pass
saveReviews: false # persist full review output to .ralpi/reviews/ (only with autoReview)
maxReviewRetries: 2 # re-executions on a 'fail' verdict before giving up
reviewBlockOnFail: false # true = mark task failed after retries exhausted instead of merging
implModel: "" # model for task impl (empty = inherit parent session model)
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: 0 # timeout for auto-commit agent sessions (0 = inherit)
reviewTimeoutMs: 0 # timeout for auto-review agent sessions (0 = inherit)
loopTimeoutMs: 0 # max total loop duration in ms (0 = no limit; checked between batches)
worktrees: parallel # "never" | "parallel" (default) | "always" — git worktree isolation
prompts:
projectContext: "Additional context for all tasks"
reflectionPrompt: "" # custom suffix for reflection extraction
```
> `execution.models` uses slot-aware round-robin: with 3 models and 2 concurrent
@@ -140,8 +230,9 @@ prompts:
> **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
> **NOTE**: model lists are only used in parallel execution. In sequential mode
> (or parallel mode with no `models` list) the parent pi session's model is used,
> unless `implModel` is set.
#### Auto-review and Auto-commit
@@ -158,19 +249,27 @@ state — original work plus fixes. On pass, the changes are already
committed and the worktree merges.
When `autoReview` is disabled, `autoCommit` runs a follow-up commit
agent after each task with no review. Both options can be overridden at
loop startup via a selection prompt (config YAML values are honored
without prompting when set explicitly).
agent after each task with no review. With `autoReview` on, the user is
also asked whether to persist full review output to
`.ralpi/reviews/<prdKey>/<task-id>.json` (`saveReviews` — this is what
enables review feedback recovery when resuming interrupted loops). Both
options can be overridden at loop startup via a selection prompt (config
YAML values are honored without prompting when set explicitly).
`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).
(used whenever no round-robin model is assigned — sequential mode, or parallel
mode with an empty `models` list; 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
```
.ralpi/progress.json # Execution progress (supports multiple PRDs)
.ralpi/loop-active.json # Active-loop marker used for auto-resume after a reload
.ralpi/reflections/ # Per-task reflections
.ralpi/reviews/<prdKey>/ # Full review output (when saveReviews is on)
.ralpi/prompts/ # Generated prompts (timestamped, for debugging)
.ralpi/config.yaml # Project-level config (optional)
```