Michael Freno
74c9ead7af
Previous flow reviewed uncommitted changes, so when a task agent self-committed its work the review was silently skipped (no uncommitted changes → review loop body never entered). This caused reviews to fire inconsistently across tasks. New review-gated flow (when autoReview is on): 1. Execute task 2. Ensure committed — commit session fallback when the agent didn't self-commit (handles both self-commit and no-commit agents) 3. Review the COMPLETE task diff (baseRef..HEAD) captured before execution, so the reviewer sees all commits not just the latest 4. On fail → re-execute with feedback → commit → re-review (same baseRef, so reviewer sees complete state including fixes) 5. On pass → merge worktree (all changes already committed) Commit is now mandated when autoReview is on (autoCommit forced true, not asked at startup). autoCommit only asked when autoReview is off. Add captureGitHead + getCommitRangeDiff helpers to utils.ts. Switch review prompt from buildReviewPromptUncommitted to buildReviewPrompt (reviewing committed changes, not uncommitted).
177 lines
6.2 KiB
Markdown
177 lines
6.2 KiB
Markdown
# 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 # 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)
|
|
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-review and Auto-commit
|
|
|
|
At loop startup the review question is asked FIRST. When `autoReview` is
|
|
enabled, commit is **mandated** — after task execution, changes are
|
|
committed (via a commit agent session when the task agent didn't
|
|
self-commit), then the complete task diff (`baseRef..HEAD`) is reviewed
|
|
against the task description. On a `fail` verdict the task is
|
|
re-executed with the review feedback injected into the prompt (looping
|
|
until the review passes or `maxReviewRetries` is exhausted). After
|
|
re-execution, changes are committed again and the full diff is
|
|
re-reviewed with the same base ref so the reviewer sees the complete
|
|
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).
|
|
|
|
`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
|