Michael Freno
087c64ff18
- Cap commit diffs in review/commit prompts at 50KB to prevent context window overflow on follow-up sessions - Skip skills catalog (noSkills) in commit/review follow-up sessions for leaner context - Wire Pi's SettingsManager into runAgentSession so Pi's built-in retry (exponential backoff, provider retry) applies to ralpi sessions — removes ralpi's duplicate manual retry loop - Remove maxRetries/retryDelayMs from ralpi config; rely on Pi's retry.* settings (with manual override support) - Remove retries field from progress.json and incrementRetry() from ProgressTracker - Add model failover to follow-up sessions (commit/review cycle through the model pool on connection errors) - Namespace reflection files by PRD key under .ralpi/reflections/<prdKey>/ so task sets don't overwrite each other - Skip loop-startup prompts for config fields explicitly set in YAML - Remove (default) annotations from loop options prompts - Default commitTimeoutMs/reviewTimeoutMs to 0 (inherit Pi defaults)
5.5 KiB
Ralpi
Execute tasks from task files until done using DAG-based dependency resolution with persistent progress tracking.
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
- [ ] 01: Setup project structure
- [ ] 02: Implement auth
- [ ] 03: Build API
YAML Format
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:
- [ ] 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 |
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.modelsuses 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